Check in tickets from a gate scanner

A scanner at the door reads the ticket code and checks the guest in. The API makes the same decision as the vendor panel's check-in screen, so the panel and your scanner always agree.

Scopes: events:read to list events, events:checkin to check tickets in.

Find the event

GET /v1/events
Authorization: Bearer xq_live_…

The answer lists your Space's events, latest event date first, in data, with has_more. Page with limit and offset. Use the event's id in the check-in call.

Check a ticket in

POST /v1/events/{id}/check-ins
Authorization: Bearer xq_live_…
Idempotency-Key: gate-3-scan-20261008-091244-001
Content-Type: application/json

{ "code": "TKT-8F2K1Q" }

You can send the code with or without the TKT- prefix, in upper or lower case.

A ticket that can be checked in, or was already checked in, answers 200. The body has a check_in object:

{
  "check_in": {
    "result": "checked_in",
    "event_id": "…",
    "ticket": { "id": "…", "code": "TKT-8F2K1Q", "event_id": "…", "status": "used", "used_at": "…" },
    "sessioned": false,
    "just_checked_in": true
  }
}

Answer	What it means	Scanner shows
200, result: checked_in	Checked in now	Green
200, result: already_used	Was already checked in	Amber: "already in"
200, result: door_admitted	Multi-session event: admitted at the door now	Green
200, result: already_admitted	Multi-session event: was already admitted at the door	Amber: "already in"
404 not_found	No such event in your Space, or no ticket with this code for this event	Red
409 cancelled · 409 expired	The ticket is cancelled or expired	Red
409 not_eligible	The ticket is in another state that cannot be checked in	Red
409 race_lost	Another scanner checked it in at the same moment	Amber: re-scan shows "already in"
503 temporarily_unavailable	We could not check the event or ticket right now	Retry with the same Idempotency-Key

just_checked_in is true only when this call admitted the guest. Use it to choose between green and amber.

A ticket of another event, or of another Space, answers 404. It is never checked in.

A re-scan is safe: a guest is never checked in twice.

Events with sessions

For a multi-session event (sessioned: true), a door check-in admits the guest but does not use up the ticket, so scanning for each session still works afterwards.

Offline scanners

Queue scans on the device with one Idempotency-Key per scan, and send them when the device is back online. A scan sent twice with the same key gets the first answer back.

Webhook

Subscribe to event.ticket.checked_in to update a live headcount elsewhere. See Webhook events.