Promoter guest lists

Promoter guest lists are part of Promoter +. Each guest list program gives its promoters a personal link; guests sign up through it for the current party, and promoters or your team can add guests by name. These endpoints read and manage one event’s guests across all promoters. They are separate from the manual guest list, which issues free tickets.

Use an organizer account Bearer token and Accept: application/json. Reads accept a read or write token; adding, removing and checking in need a write token. Personal co-organizer tokens see, add and remove only the guests of programs they manage (programs whose selected events are all assigned to them, never shop-wide ones). Promoter sessions cannot use these endpoints; promoters manage their own guests in the promoter app. An event that does not exist or is not accessible returns 404.

:id is the guest’s opaque public ID, not a database number.

List guests

GET /admin/events/:slug/promoter_guests returns every guest of the event, sorted by name. The list is not paginated.

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  "https://app.usetix.io/admin/events/friday-club-night/promoter_guests?filter=expected"

Response:

{
  "event": {
    "slug": "friday-club-night",
    "title": "Friday Club Night"
  },
  "summary": {
    "guests": 48,
    "heads": 97,
    "arrived": 61
  },
  "guests": [
    {
      "id": "GUEST_PUBLIC_ID",
      "name": "Anna Müller",
      "email": "anna@example.com",
      "instagram": "anna.m",
      "companions": 1,
      "party_size": 2,
      "note": "Table 4",
      "source": "link",
      "channel": "instagram",
      "attribution": { "utm_source": "ig", "utm_campaign": "story-friday" },
      "promoter": {
        "membership_id": 42,
        "name": "Lisa Promo",
        "code": "LISA"
      },
      "checked_in_at": null,
      "checked_in_count": null,
      "marketing_consent_at": "2026-10-02T18:12:40Z",
      "created_at": "2026-10-02T18:12:40Z"
    }
  ]
}

summary counts all of the event’s guests you can see, regardless of the filters: guests entries, heads (guests plus companions) and arrived (heads checked in). guests follows the filters.

Guest details are kept for 90 days after the event. After that the entry reads “Removed guest” without email, Instagram handle or note; the counts stay.

The same list is available as a spreadsheet at /admin/events/:slug/promoter_guests.csv, with the same filters.

Add a guest

Add a guest for one of the promoters through their personal code. promo_code_id is the numeric id from the program’s promo_codes array (see Promoter programs). The code, its promoter and its guest list program must be active, you must be able to manage the program, and the program must cover the event; any other code returns 404.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"guest": {"promo_code_id": 17, "name": "Ben Guest", "email": "ben@example.com", "companions": 2, "note": "Friend of the DJ"}}' \
  https://app.usetix.io/admin/events/friday-club-night/promoter_guests

Success returns 201 Created with the guest object, source set to staff. Your team can add guests until the event ends, also after the list closed for sign-ups at doors open. A guest with an email gets the same confirmation as a guest who signed up through the link. The activity log records the addition, naming the event, not the guest.

Failures return 422 Unprocessable Entity with { "errors": { "field": ["message"] } }. Expect errors.base when the list is closed (the event is over, unpublished or archived, or the shop has no Promoter + or is not live) or full (guest_capacity reached), and errors.email when the email is already on the event’s list.

Remove a guest

DELETE /admin/events/:slug/promoter_guests/:id removes the guest and returns 204 No Content. The activity log records it, naming the event, not the guest.

Check in

POST /admin/events/:slug/promoter_guests/:id/check_in checks a guest in. Pass an optional count when only part of the party came; it is clamped between 1 and the guest’s party_size, which is the default. Checking in again changes the count and keeps the first check-in time. DELETE on the same URL undoes the check-in. Both return the guest object.

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"count": 2}' \
  https://app.usetix.io/admin/events/friday-club-night/promoter_guests/GUEST_PUBLIC_ID/check_in

Check-ins follow event access: co-organizers can check in any promoter guest of their assigned events, as they can at the door. Door apps use the scanner’s door guest list, which leaves out emails.