Docs/Documentation/Learn

List Guests

Search and retrieve guest profiles across all reservations — names, contact details, stay history, and lifetime revenue.

When to use this endpoint

Build a guest CRM with unified profiles from all platforms
Search for returning guests by name, email, or phone
Export guest data for marketing campaigns or loyalty programs
Identify high-value repeat guests based on stay count and revenue

Need full guest details?

Use GET /v1/guests/:id to fetch a single guest with all contacts, reservation history, and custom fields.

List guests

GET/v1/guests

curl "https://api.repull.dev/v1/guests?q=Sarah&limit=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Query parameters

limitintegerDefault: 50

Maximum number of results to return.

offsetintegerDefault: 0

Number of results to skip for pagination.

searchstring

Search across guest name, email, and phone number. Supports partial matching.

Response format

Returns a paginated array of guest objects with aggregated stay and revenue data.

{
  "data": [
    {
      "id": "789",
      "firstName": "Sarah",
      "lastName": "Mitchell",
      "email": "sarah@example.com",
      "phone": "+1-555-0123",
      "language": "en",
      "totalStays": 3,
      "totalRevenue": 4200,
      "lastStay": "2026-06-05",
      "createdAt": "2025-08-15T09:00:00Z"
    },
    {
      "id": "812",
      "firstName": "Sarah",
      "lastName": "Chen",
      "email": "sarah.chen@example.com",
      "phone": "+44-20-7946-0958",
      "language": "en",
      "totalStays": 1,
      "totalRevenue": 1800,
      "lastStay": "2026-05-20",
      "createdAt": "2026-04-10T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  }
}

Response fields

idstring

Unique guest identifier.

firstNamestring

Guest first name.

lastNamestringnullable

Guest last name.

emailstringnullable

Primary email address.

phonestringnullable

Primary phone number.

languagestring

Preferred language (ISO 639-1).

totalStaysinteger

Total number of completed reservations.

totalRevenuenumber

Lifetime revenue from this guest (in account default currency).

lastStaystringnullable

Check-out date of most recent stay (YYYY-MM-DD).

createdAtstring

ISO 8601 timestamp when the guest record was created.

Filtering examples

Search by name

curl "https://api.repull.dev/v1/guests?search=Mitchell" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Search by email

curl "https://api.repull.dev/v1/guests?search=sarah@example.com" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Search by phone

curl "https://api.repull.dev/v1/guests?search=555-0123" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Pagination

Results are cursor-paginated. Pass the previous response's pagination.nextCursor back as cursor, and stop when pagination.hasMore is false.

// Export all guests for a CRM sync
let cursor: string | undefined

do {
  const { data, pagination } = await repull.guests.list({ limit: 50, cursor });

  for (const guest of data) {
    await syncToCRM(guest);
  }

  cursor = pagination.hasMore ? pagination.nextCursor ?? undefined : undefined;
} while (cursor);

API Reference

See the complete Guests API Reference for all endpoints including get profile and create guest.

Previous← Update Pricing NextList Conversations →