Guest List

Guest list entries are the people requested onto the list for a given tour day, with pass allocations and an approval status. Guest list entry IDs are integers. All endpoints require the standard authentication headers.

List guest list

GET /v1/tours/{tourId}/days/{dayId}/guestlist

Returns the guest list for one day of a tour. Scope: guestlist.read Example

curl "$BASE/v1/tours/2f1c…/days/1843/guestlist" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" -H "Authorization: Bearer $TOKEN"

Path parameters

Name	Type	Description
`tourId`	string (UUID)	The tour.
`dayId`	integer	The day within the tour.

Response data — array of guest list entries:

{
  "id": 77,
  "firstName": "Sam",
  "lastName": "Taylor",
  "email": "sam@…",
  "affiliation": "Press",
  "numberOfGuests": 2,
  "notes": "Photo pit access",
  "status": { "id": 1, "type": "APPROVED", "description": "Approved" },
  "created_by": { "id": "…", "firstname": "Jane", "lastname": "Doe" },
  "day": { "id": 1843, "name": "Day 1", "date": "2026-06-01T00:00:00Z" },
  "tour": { "id": "2f1c…", "name": "Spring Tour 2026" },
  "is_deleted": false,
  "created_at": "2026-05-18T08:00:00Z",
  "updated_at": "2026-05-20T08:00:00Z"
}

Response fields — the GET response returns a fixed subset of fields, which differs from what create/edit accept. It does not include passes, pickupMethod, venue, or avatarColor:

Field	Type	Description
`id`	integer	Guest list entry ID.
`firstName`	string	Guest first name.
`lastName`	string	Guest last name.
`email`	string	Guest email (may be `null`).
`affiliation`	string	Guest affiliation (may be `null`).
`numberOfGuests`	integer	Party size.
`notes`	string	Notes (may be `null`).
`status`	object	`{ id, type, description }`.
`created_by`	object	`{ id, firstname, lastname }`.
`day`	object	`{ id, name, date }`.
`tour`	object	`{ id, name }`.
`is_deleted`	boolean	Soft-delete flag.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

Add to guest list

POST /v1/guestlist

Scope: guestlist.write Body

Field	Type	Required	Description
`tour_id`	string (UUID)	Yes	Tour the entry belongs to.
`day_id`	number	Yes	Day the entry is for.
`firstName`	string	Yes	Guest first name.
`lastName`	string	Yes	Guest last name.
`numberOfGuests`	number	Yes	Party size.
`pickupMethodId`	number	Yes	How the guest collects passes — valid values.
`statusId`	number	Yes	Approval status — valid values.
`passes`	array<Pass>	Yes	Pass allocations — see Pass object.
`email`	string	No	Guest email.
`affiliation`	string	No	Guest affiliation.
`notes`	string	No	Free-text notes.
`requesterId`	string	No	Who requested the entry.
`venueId`	number	No	Associated venue.
`avatarColorId`	number	No	Avatar colour — valid values.

Response data: { "id": 77 }.

Edit a guest list entry

PUT /v1/guestlist/{guestListId}

Scope: guestlist.write Path parameters

Name	Type	Description
`guestListId`	integer	The entry to edit.

Body — note several fields remain required on edit:

Field	Type	Required	Description
`firstName`	string	Yes	Guest first name.
`lastName`	string	Yes	Guest last name.
`numberOfGuests`	number	Yes	Party size.
`pickupMethodId`	number	Yes	Pickup method — valid values.
`statusId`	number	Yes	Approval status — valid values.
`passes`	array<Pass>	Yes	Pass allocations — see Pass object.
`email`, `affiliation`, `notes`, `requesterId`, `venueId`	—	No	As in create.

The guestListId is taken from the URL path — do not send it in the request body.

Response data: { "id": 77 }.

Pass object

Each entry in the passes array allocates a number of passes of a given pass type to the guest.

"passes": [
  { "passId": 1, "count": 2 },
  { "passId": 3, "count": 1 }
]

Field	Type	Required	Description
`passId`	number	Yes	ID of a pass type on this tour — from List pass types.
`count`	number	Yes	Number of passes of this type to allocate to the guest.

Delete a guest list entry

DELETE /v1/guestlist/{guestListId}

Soft-deletes the entry. Reversible with Restore a guest list entry. Scope: guestlist.write Path parameters

Name	Type	Description
`guestListId`	integer	The entry to delete.

Response data: none.

Restore a guest list entry

POST /v1/guestlist/{guestListId}/restore

Restores a soft-deleted entry, along with its pass allocations. Scope: guestlist.write Path parameters

Name	Type	Description
`guestListId`	integer	The entry to restore.

Response data: none.

Update entry statuses in bulk

PUT /v1/tours/{tourId}/guestlist/status

Moves several entries to new statuses in one call — approving or declining a day’s requests, for example. Scope: guestlist.write Path parameters

Name	Type	Description
`tourId`	string (UUID)	The tour the entries belong to.

Body

Field	Type	Required	Description
`list`	array<StatusChange>	Yes	1–500 entries.

StatusChange object

Field	Type	Required	Description
`id`	integer	Yes	Guest list entry ID, from List guest list.
`statusId`	integer	Yes	New status — valid values.

Every ID must belong to the tour in the path. A single foreign or unknown ID rejects the whole batch with 403 and changes nothing — the call is all-or-nothing, so a partial success is never something you have to reconcile.

Example

curl -X PUT "$BASE/v1/tours/2f1c…/guestlist/status" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "list": [ { "id": 77, "statusId": 1 }, { "id": 78, "statusId": 1 } ] }'

Response data: none.

Prefer this over looping Edit a guest list entry, which requires the guest’s full record on every call. A repeated ID in list is fine — the last entry for an ID wins.

Approved-guest total for a day

GET /v1/tours/{tourId}/days/{dayId}/guestlist/approved-count

Returns the total number of guests across the day’s approved entries — the figure a day’s cap is checked against. Scope: guestlist.read Path parameters

Name	Type	Description
`tourId`	string (UUID)	The tour.
`dayId`	integer	The day.

Response data: a number.

{ "status": true, "message": "Success", "data": 24 }

This is a sum of party sizes (numberOfGuests), not a row count — twelve approved entries of two guests each answer 24. It is not derivable from a paged List guest list response, which is why it has its own endpoint. null means no approved entries.

Configure a day’s guest list

PUT /v1/tours/{tourId}/days/{dayId}/guestlist/config

Sets the day’s guest cap, lock state, request cut-off and per-pass-type allocation caps. Scope: guestlist.write — requires the user to be a tour admin. Path parameters

Name	Type	Description
`tourId`	string (UUID)	The tour.
`dayId`	integer	The day.

Body — at least one field is required.

Field	Type	Required	Description
`totalGuest`	number	Together with `enforceTotal`	Total guests allowed on the day.
`enforceTotal`	boolean	Together with `totalGuest`	Whether `totalGuest` is enforced.
`guestlist_locked`	boolean	No	Lock the list so no further requests can be added.
`guestlist_cutoff`	ISO 8601 datetime	No	Request cut-off, interpreted in the venue’s time zone. Send `null` to clear.
`remove_cutoff`	boolean	No	Clear the cut-off.
`passes`	array<PassConfig>	No	Per-pass-type caps, up to 200 entries.
`venue_id`	number	No	Configure one venue on the day instead of the day’s own defaults.

PassConfig object

Field	Type	Required	Description
`passId`	number	Yes	Pass type — from List pass types.
`total`	number	Yes	How many of this pass are available.
`enforce`	boolean	Yes	Whether that total is enforced.

totalGuest and enforceTotal are written as one change and must be sent together — one without the other is rejected with 400 rather than being silently dropped.An empty body is also a 400: name at least one thing to change.Setting a day-level guestlist_cutoff resolves the time against the time zone of a venue on that day, so a day with no venue yet returns 400 — add a venue, or set the cut-off per venue by passing venue_id.

Response data: none.

List pass types

GET /v1/tours/{tourId}/passTypes

Returns the tour’s pass types — the source of the passId values used in the Pass object. Scope: guestlist.read Path parameters

Name	Type	Description
`tourId`	string (UUID)	The tour.

Query parameters — optional.

Name	Type	Description
`limit`	number	Max pass types to return.
`offset`	number	Number to skip.

Response data — array of pass types, each with its name, abbreviation, material, days, venues and visibility.

A pass type restricted away from the authenticated user is not returned at all.

Create a pass type

POST /v1/tours/{tourId}/passTypes

Scope: guestlist.write — requires the user to be a tour admin. Body

Field	Type	Required	Description
`name`	string	Yes	Pass type name, e.g. `Guest List`. Unique within the tour.
`abbv`	string	Yes	Short label shown on the pass, e.g. `GL`. Unique within the tour.
`day_ids`	array<integer>	Yes	Days this pass type applies to. Non-empty.
`description`	string	No	Longer description.
`materialTypeId`	number	No	Pass material — valid values.
`attachment`	Attachment	No	Artwork or reference file.
`venue_ids`	array<integer>	No	Venues this pass type applies to.
`isEveryone`	boolean	No	Visible to everyone on the tour. This is the default when you send no visibility field.
`isAdminOnly`	boolean	No	Restrict to tour admins only. Mutually exclusive with `isEveryone`.
`visibilityList`	array<string (UUID)>	No	Share with specific users.
`invitesVisibilityList`	array<integer>	No	Share with specific pending invites.

Note the singular isAdminOnly here. Schedule items, venues and stays spell the same flag isAdminsOnly; pass types do not.

Response data: { "id": 9 }.

Update a pass type

PUT /v1/passTypes/{passTypeId}

Scope: guestlist.write — requires the user to be a tour admin. Path parameters

Name	Type	Description
`passTypeId`	integer	The pass type to update.

Body — a full record, not a delta.

Field	Type	Required	Description
`name`	string	Yes	Pass type name.
`abbv`	string	Yes	Short label.
`tour_id`	string (UUID)	Yes	The tour the pass type belongs to.
`day_ids`	array<integer>	Yes	Replaces the set of days this pass type applies to.
`venue_ids`	array<integer>	No	Replaces the venue set.
`description`, `materialTypeId`, `attachment`, `attachments`	—	No	As in create.
`isEveryone`, `isAdminOnly`, `visibilityList`, `invitesVisibilityList`	—	No	As in create.
`takeOverOwnership`	boolean	No	Become the owner while making a public pass type private.
`removeCreatorAccess`	boolean	No	With `takeOverOwnership`, drop the previous owner from the audience.

name, abbv, tour_id and day_ids are required on update, and day_ids replaces the day set rather than adding to it. Read the current values from List pass types and resend them with your changes, or the pass type will silently stop applying to days you omitted.

Response data: { "id": 9 }.

Delete a pass type

DELETE /v1/passTypes/{passTypeId}?force=true

Scope: guestlist.write — requires the user to be a tour admin. Query parameters

Name	Type	Description
`force`	boolean	Delete even when guests hold this pass. Omit it first — see below.

Without force, this is a safe check that deletes nothing. If any guest still holds the pass, the response is 200 with status: false, the message This Pass is being used in guests requests, and the blocking entries in data.guestLists — check status, not just the HTTP code.With force=true those pass allocations are deleted too, and any guest left holding no pass at all is soft-deleted with them.

Response data when the delete was blocked:

{
  "status": false,
  "message": "This Pass is being used in guests requests",
  "data": {
    "guestLists": [
      { "id": 77, "firstName": "Sam", "lastName": "Taylor", "numberOfGuests": 2 }
    ]
  }
}

On a successful delete: status: true and no data. Reversible with Restore a pass type.

Restore a pass type

POST /v1/passTypes/{passTypeId}/restore

Restores a soft-deleted pass type, along with the guest allocations and guest list entries that were removed with it. Scope: guestlist.write — requires the user to be a tour admin. Response data: none. A pass type that is not deleted returns 400.

List requesters

GET /v1/tours/{tourId}/requesters

Returns the tour users who can be set as an entry’s requesterId. Scope: guestlist.read Response data: array of tour users.

See also: Tours, Bulletins, Reference Data.

Get started

Endpoints

Guides

Reference

List guest list

Add to guest list

Edit a guest list entry

Pass object

Delete a guest list entry

Restore a guest list entry

Update entry statuses in bulk

Approved-guest total for a day

Configure a day’s guest list

List pass types

Create a pass type

Update a pass type

Delete a pass type

Restore a pass type

List requesters

​List guest list

​Add to guest list

​Edit a guest list entry

​Pass object

​Delete a guest list entry

​Restore a guest list entry

​Update entry statuses in bulk

​Approved-guest total for a day

​Configure a day’s guest list

​List pass types

​Create a pass type

​Update a pass type

​Delete a pass type

​Restore a pass type

​List requesters

List guest list

Add to guest list

Edit a guest list entry

Pass object

Delete a guest list entry

Restore a guest list entry

Update entry statuses in bulk

Approved-guest total for a day

Configure a day’s guest list

List pass types

Create a pass type

Update a pass type

Delete a pass type

Restore a pass type

List requesters