Guests

Guest profiles with contact information.

List guests with search

GET/v1/guests

Request

curl https://api.repull.dev/v1/guests?limit=20 \
  -H "Authorization: Bearer $REPULL_API_KEY"

Response

{
  "data": [
    {
      "id": "123",
      "displayName": "Example",
      "displayNameLong": "Example",
      "avatarUrl": "https://example.com/...",
      "language": "Example text",
      "country": null,
      "phone": "+15550000000",
      "email": "guest@example.com",
      "totalReservations": 0,
      "totalRevenue": "Example text",
      "lastStayedAt": null,
      "firstStayedAt": null,
      "createdAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true,
    "total": 0
  }
}

Captured from a real response. Regenerated on every release, and CI fails if this shape stops matching the API.

Query Parameters

cursorstring

Opaque cursor returned in the previous response's `pagination.nextCursor`. Omit to fetch the first page.

offsetinteger

First-class alias for cursor-based pagination. Mutually exclusive with `cursor` — passing both returns 422. Accepts integers in `[0, 10000]`; deeper walks must use `cursor` (constant per-page cost). The response always includes `pagination.nextCursor` so consumers can switch from offset → cursor mid-walk for deep pagination without re-keying.

limitinteger

Max items per page. Hard cap is 100.

qstring

Case-insensitive substring search on name, email, or phone.

has_reservationboolean

Restrict to guests that do (`true`) or do not (`false`) have any reservation on file.

listingIdinteger

Restrict to guests with at least one reservation on the given internal Repull listing id.

Get a guest profile by ID

GET/v1/guests/:id

Request

curl https://api.repull.dev/v1/guests/789 \
  -H "Authorization: Bearer $REPULL_API_KEY"

Response

{
  "id": "123",
  "displayName": "Example",
  "displayNameLong": "Example",
  "avatarUrl": "https://example.com/...",
  "language": "Example text",
  "country": null,
  "phone": "+15550000000",
  "email": "guest@example.com",
  "totalReservations": 0,
  "totalRevenue": "Example text",
  "currency": "USD",
  "isBlacklisted": false,
  "blacklistedReason": null,
  "riskLevel": "low",
  "verificationLevel": 0,
  "createdAt": "2026-06-01T12:00:00.000Z",
  "contacts": [
    {
      "type": "email",
      "value": "Example text",
      "verified": false,
      "isPrimary": true,
      "lastUsed": null
    }
  ],
  "flags": [],
  "notes": [],
  "reservationsSummary": {
    "total": 0,
    "future": 0,
    "past": 0,
    "cancelled": 0
  }
}

Captured from a real response. Regenerated on every release, and CI fails if this shape stops matching the API.

Create a new guest

POST/v1/guests

Note

Find-or-create: read `created` on the response. With `provider`, the guest is created in that PMS first and `pms.externalId` is its id there; a PMS whose API cannot create guest profiles (Hostaway) is 422 pms_write_unsupported and nothing is created. GET /v1/connect/{provider} → capabilities.pms.guests.create says so beforehand. Guide: /docs/pms-writes#guests

Request

curl -X POST https://api.repull.dev/v1/guests \
  -H "Authorization: Bearer $REPULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Marco",
  "lastName": "Rossi",
  "language": "it"
}'

Response

{ "data": { "id": "790", "firstName": "Marco", ... } }

Body Parameters

firstNamestringRequired

lastNamestring

emailstring

phonestring

E.164 preferred. Stored normalised.

languagestring

BCP-47 tag.

currencystring

isBusinessTravelerboolean

providerstring

A connected PMS to create the guest in as well, e.g. `guesty`. Created there first; its id comes back as `pms.externalId`.

Update a guest — in its PMS too, when linked to one

PATCH/v1/guests/:id

Note

Send at least one field; only those change. A guest linked to a connected PMS (created with `provider`, or imported from one) is changed in that PMS first, and `pms` lists each PMS the change reached with the sections it applied. A PMS whose API cannot change guest profiles (Hostaway) is 422 pms_write_unsupported and nothing is written; a revoked PMS connection is 403 connection_reauth_required. GET /v1/connect/{provider} → capabilities.pms.guests.update says so beforehand. Guide: /docs/pms-writes#guests

Request

curl -X PATCH https://api.repull.dev/v1/guests/790 \
  -H "Authorization: Bearer $REPULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lastName": "Rossi",
  "email": "marco.rossi@example.com"
}'

Response

{
  "id": 790,
  "firstName": "Marco",
  "lastName": "Rossi",
  "language": "it",
  "contacts": [{ "type": "email", "value": "marco.rossi@example.com", "isPrimary": true }],
  "updatedAt": "2026-10-03T14:02:11Z",
  "pms": [{ "provider": "guesty", "applied": ["guest"] }]
}

Body Parameters

firstNamestring

lastNamestring

emailstring

Added as the guest's newest email; earlier ones are kept.

phonestring

E.164 preferred. Added as the guest's newest phone; earlier ones are kept.

languagestring

BCP-47 tag.