Send us a guest list¶

POST /external/v1/guest-list-import adds names to one venue's guest list for one business date. It creates guest list entries only, not a reservation or a payment. It needs the guest-lists:write permission.

curl -X POST "https://production.speakeasygo.com/external/v1/guest-list-import?venueId=11111111-1111-4111-8111-111111111111&businessDate=2026-11-14" \
  -H "token: $SPEAKEASY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a54-7b1e-4a53-9f55-1c6a0e8b2d11" \
  -d '[
    { "firstName": "Sam", "lastName": "Sample", "guests": { "total": 4 } },
    { "firstName": "Alex", "lastName": "Example", "guests": { "male": 2, "female": 3 }, "notes": "Birthday" }
  ]'

The request¶

Query parameter	Meaning
`venueId`	The venue, a UUID from `GET /external/v1/venues`
`businessDate`	A date on the venue's calendar, `YYYY-MM-DD`. Not a UTC date.

A date has passed once the venue's next business day is about to start: the entries expire one minute before it. An expired date gets a 400 with GUEST_LIST_IMPORT_DATE_EXPIRED.

The body is a list of 1 to 250 entries, and at most 512 KiB.

Field	Required	Rules
`firstName`	Yes	Up to 100 characters, not blank
`lastName`	Yes	Up to 100 characters, not blank
`guests`	Yes	Either `total` (1 to 100), or `male` and `female` together, adding up to 1 to 100
`notes`	No	Up to 1,000 characters

Unknown fields in an entry are refused.

All or nothing. Every entry is checked first. If one fails, nothing is saved.

The answer¶

201 with one line per entry you sent. index counts from 0.

{
  "operationId": "7a1f3c9e-52b4-4f0a-9c55-0a6d1e7b3f21",
  "venueId": "11111111-1111-4111-8111-111111111111",
  "businessDate": "2026-11-14",
  "attribution": null,
  "createdCount": 2,
  "entries": [
    { "index": 0, "guestListEntryId": "0b6e7a1c-3c5d-4e2f-8a91-6d2f4b7c9e10" },
    { "index": 1, "guestListEntryId": "9c2d5f8a-1e3b-4a7c-b6d4-2f8e1c5a7b30" }
  ],
  "createdAt": "2026-11-05T12:00:00.000Z"
}

attribution shows the team member the entries are credited to, if your integration has one. See Team member credit.

Retries¶

Idempotency-Key is required. A retry with the same key and the same list gives you the first answer, and adds nothing. See Safe retries.

Errors¶

Status	Code	What it means
`400`	`GUEST_LIST_IMPORT_VALIDATION_FAILED`	An entry or parameter is not valid. See `errors`.
`400`	`GUEST_LIST_IMPORT_DATE_INVALID`	`businessDate` is not a real date
`400`	`GUEST_LIST_IMPORT_DATE_EXPIRED`	That business date is over
`400`	`GUEST_LIST_IMPORT_VENUE_CONFIGURATION_INVALID`	The venue is not set up for imports yet
`403`	`GUEST_LIST_IMPORT_NOT_AUTHORIZED`	The credited team member is not active at this venue
`404`	`GUEST_LIST_IMPORT_VENUE_NOT_FOUND`	Your key cannot reach this venue
`413`		The body is over 512 KiB
`429`	`GUEST_LIST_IMPORT_REQUEST_RATE_LIMIT_EXCEEDED` and others	See Rate limits