Guests

Scope read:guests. This scope carries personal data, so it is never pre-selected when a key is created — the agency ticks it deliberately, and the portal marks keys that hold it.

What is never returned

Identity documents captured at check-in — passport numbers, issue and expiry dates, the scanned identity name — are encrypted per booking and deleted on a retention schedule. They are not available through this API, in any form, and cannot be written through it either. A copy handed out here would outlive the deletion somewhere nobody can reach, which is the one thing the encryption exists to prevent.

What you get is ordinary master data: who the guest is and how to reach them.

`GET /partner/v1/guests`

Query parameter	Required	Meaning
`search`	no	Applied from 2 characters; matches first name, last name, e-mail or phone
`stage`	no	`prospect` (presales conversation, no stay yet) or `customer`
`page`	no	1-based page number, default 1
`pageSize`	no	1–200, default 100; newest first

{
  "guests": [
    {
      "id": "0191b…",
      "firstName": "Nadia",
      "lastName": "Rahman",
      "email": "nadia@example.com",
      "phone": "+971 50 123 4567",
      "nationality": "AE",
      "stage": "customer",
      "presales": null,
      "convertedAt": "2026-08-20T09:02:11.000Z",
      "createdAt": "2026-08-15T10:48:52.752Z"
    },
    {
      "id": "0191d…",
      "firstName": "Omar",
      "lastName": "K.",
      "email": null,
      "phone": "+971 55 000 0000",
      "nationality": null,
      "stage": "prospect",
      "presales": { "expectedArrival": "2026-11-01", "expectedNights": 30, "preferredUnitId": "0190c…", "region": "Dubai", "district": "Marina", "adults": 2, "children": 0, "wishes": "sea view, near the tram" },
      "convertedAt": null,
      "createdAt": "2026-09-01T16:30:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalItems": 312,
  "pageCount": 4
}

Prospects

A prospect is a presales record: someone who walked in or called, whose wishes the office noted, and who has not booked yet. presales carries what they are looking for; the exact fields follow the office’s presales form and may grow. A booking converts the record to customer and stamps convertedAt.

`GET /partner/v1/guests/:id`

The same record plus that guest’s stays — references, not details:

{
  "guest": {
    "id": "0191b…",
    "firstName": "Nadia",
    "lastName": "Rahman",
    "email": "nadia@example.com",
    "phone": "+971 50 123 4567",
    "nationality": "AE",
    "createdAt": "2026-08-15T10:48:52.752Z",
    "stays": [
      {
        "id": "0191a…",
        "unitSlug": "marina-loft-2br",
        "arrival": "2026-09-10",
        "departure": "2026-09-14",
        "status": "confirmed"
      }
    ]
  }
}

stays is capped at the 100 most recent. Each entry’s id works with GET /bookings/:id.

404 NOT_FOUND for an unknown id or a guest of another agency.

Handling it

You are processing someone else’s guests’ personal data. Store the minimum your integration actually needs, honour deletion requests by deleting your copy too, and remember that the agency — not you — answers to the guest for it.