Access Control Integration
Connect your venue access control system with SECUTIX to manage ticket validation at entry points. The integration follows a list-based pattern: your access control backend periodically downloads ticket lists (allowed and denied tickets) from SECUTIX, pushes them to your gate devices, and reports scan results back to SECUTIX for business intelligence, attendance tracking, and real-time venue filling monitoring.
These APIs integrate an access control system — the backend that manages a venue's gates — with the SECUTIX ticketing platform. They are not meant to be called by an access control device (turnstile, handheld scanner, validation app).
A device never talks to SECUTIX directly: it is driven by an access control system, which downloads the ticket lists from SECUTIX, distributes them to its devices, collects their scans and reports them back. If you build or sell devices, integrate them with an access control system, and let that system integrate with SECUTIX as described here.
Example use cases
- Keep access control systems up to date with last-minute sales, cancellations, and transfers as the event approaches.
- Report scan results in real time to drive live venue-filling tracking on the seatmap, onsite support processes and to allow to apply business rules to avoid ticket misuse (transfers, reprints, etc.).
Architecture Overview
Integration Steps
The numbered steps below correspond to the flows shown in the architecture diagram.
-
Setup — Before any data flows, configure the integration between your access control system and the SECUTIX platform:
- Register an API operator to obtain OAuth 2.0 credentials (Client ID / Secret). See Authentication & Authorization.
- Ask the venue to link that operator to an access control interface in SECUTIX. The export remembers, per interface, which tickets it has already handed out, so each access control system uses its own operator. Two systems sharing one operator would steal tickets from each other.
- Decide the export scope (season, products or performances) and find its ids.
-
Export Ticket Lists — Your access control backend polls
POST /s360/v3/tickets/access/ticketliststo download the allowed and/or denied tickets with their barcodes and the details you ask for. See Exporting ticket lists below and the Export Ticket List API Reference. -
Synchronize to Devices — Your access control backend pushes the lists to its gate devices (turnstiles, handheld scanners, etc.). The format and protocol for this step depend on your device vendor — SECUTIX is not involved in this internal synchronization. All tickets — including dematerialized ones (RFID cards) — are identified by barcode.
-
Scan & Collect — At event time, your devices scan ticket barcodes and make local access decisions based on the downloaded lists. Scan results (accepted, rejected, failure reason) are collected by your access control backend. Devices that operate offline store scan results locally until connectivity is restored.
-
Report Scan Results — Your access control backend calls
POST /s360/v3/tickets/access/controlsto import the scan results into SECUTIX. This enables live venue filling tracking on the seatmap and ticket status updates in the TIXNGO app. See Importing controls below and the Import Ticket Checks API Reference.
Choose the export scope
Every export is scoped: a call must carry at least one of seasonId, productIds or performanceIds. Pick the level that matches how the venue sells:
| Venue type | Recommended scope | Why |
|---|---|---|
| Museums, exhibitions, fairs (visit passes, timed entries, open dates) | seasonId, or productIds | Tickets belong to a product valid over a period, not to a single dated show. Exporting the whole season, or the few products the gates control, covers every date in one feed. |
| Events and sports (concerts, shows, matches) | performanceIds | Gates control dated performances or matches. Export the performances the venue controls, all of them in the same call. |
For museums and fairs, prefer one export per season over a loop of one export per product. One season scope is one polling loop and one call every polling interval, whatever the number of products it contains; a loop over 50 products is 50 calls every interval for the same result.
Whatever the level, keep the number of calls low: put several ids in one call (productIds: [101, 102, 103], performanceIds: [201, 202]) instead of one export per id.
A ticket is handed out by one export only. Within the same access control system, do not run overlapping exports: a season export and a performance export inside that same season overlap, and so do two product lists sharing a product. Overlapping exports split the tickets between them, and a ticket can end up delivered to neither gate. Choose one scope, keep it, and drive it from a single client.
Find the ids in the setup endpoints
The export filters on SECUTIX ids, not codes. Read them once from the setup endpoints, with the same OAuth credentials, and store them in your access control configuration:
| You need | Call | Field to read |
|---|---|---|
seasonId | GET /s360/v3/setup/seasons | id of the season |
performanceIds — events | GET /s360/v3/setup/events?seasonId=…, or GET /s360/v3/setup/events/{eventId} | performances[].id |
performanceIds — sports (matches) | GET /s360/v3/setup/competitions?seasonId=…, or GET /s360/v3/setup/competitions/{competitionId} | performances[].id |
productIds — museums and fairs | GET /s360/v3/setup/visitpasses | id of the visit pass (its seasonId is also returned) |
The list endpoints are paginated with paginationToken / nbMaxResults: follow the token until the list is complete.
Exporting ticket lists
Request
POST /s360/v3/tickets/access/ticketlists
{
"seasonId": 1234567,
"listType": "BOTH",
"granularities": ["PRODUCT", "SEATING", "HOLDER"],
"pageSize": 1000,
"paginationToken": "…token returned by the previous call…"
}
| Field | Meaning |
|---|---|
seasonId / productIds / performanceIds | The scope. At least one is required. Keep it identical on every call of the same export. |
listType | ALLOWED (tickets to let in), DENIED (tickets to turn away) or BOTH (default). Use BOTH for an incremental feed: a ticket you already hold as valid and that has since been cancelled comes back as denied, which is how your system learns to refuse it. |
granularities | Optional blocks of detail added to each ticket: PRODUCT, SEATING, HOLDER, PURCHASER, PURCHASE_DETAILS, EXTERNAL_REFERENCE. Ask only for the blocks your gates use. |
criteriaIdCodes | Optional contact criteria of the ticket holder to publish, by id code. |
externalReferenceCodes | The external reference types published in the EXTERNAL_REFERENCE block. Only the types named here are published: none named, none published. |
pageSize | Tickets per page, default 1000, maximum 10000. The platform may cap it lower for your integration, without error. |
paginationToken | Absent on the very first call of an export; required on every later call. |
The barcode returned is exactly what a scanner reads at the gate, and what the import endpoint expects back.
How the pagination works
The export is an incremental feed that never ends, not a list you read once:
- First call — no token. SECUTIX returns the first page of the tickets in the scope and a
paginationToken. - Every following call — the last token you received. SECUTIX returns only the tickets it has not handed out yet, or that changed since (new sales, cancellations, transfers, reprints…), with a new token.
- Every answer carries a token, including an answer with no ticket. Always keep the latest one and send it on the next call.
- An empty
ticketsarray means "nothing new right now", not "end of the feed". Wait for the polling interval and call again with the token that came with this empty page. - A page smaller than
pageSizeis not the end either. Keep calling until a page comes back empty.
So the loop of your access control system is:
token = load from storage (none the very first time)
every polling interval:
repeat:
page = POST /ticketlists { scope, listType, granularities, paginationToken: token }
apply page.tickets to your whitelist / blacklist
token = page.paginationToken ← persist it, together with the tickets
until page.tickets is empty
A page is marked as handed out the moment SECUTIX returns it. If your system crashes after receiving a page but before storing it, those tickets will not be sent again. Store the tickets and the new token atomically, before asking for the next page.
The export refuses with 400 BAD_REQUEST:
- a call without token while an export of that scope is already in progress — continue with the last token instead;
- a token older than the last page served — always send the latest token you received;
- a token that was not issued by SECUTIX, or that was altered. The token is opaque: store and send it as-is.
Starting over: reset
When you lost the token, change the scope, or need to reload all tickets (new device fleet, corrupted local database), call POST /s360/v3/tickets/access/ticketlists/resets with the same scope as the export. Every ticket of the scope is put back, and the next call without token returns all of them again. See the Reset Ticket List Export API Reference.
Use a reset to recover, never as part of the regular polling loop.
Recommended polling frequency
Poll every 30 to 60 seconds per export scope. This is enough for online sales, transfers and cancellations to reach the gates before the ticket holder does.
Poll every 10 seconds only while the box office is selling for the event: a ticket bought at the box office is presented at the gate a few moments later. Go back to 30–60 seconds once the box office has closed. Never poll more often than every 10 seconds: it does not make tickets arrive faster.
When a page comes back full, call again immediately to drain the backlog; the interval applies between the empty pages.
Importing controls
Report the scans of your devices with POST /s360/v3/tickets/access/controls. The body is a list of up to 500 checks:
POST /s360/v3/tickets/access/controls
[
{
"barcode": "035971795127460976280247",
"controlDateTime": "2026-03-14T18:21:07Z",
"controlState": "OK",
"flow": "IN",
"externalControlIdentifier": "20260314-GATE-A",
"gateCode": "A",
"sectorCode": "NORTH",
"deviceCode": "SCANNER-12"
},
{
"barcode": "035971795127460976280255",
"controlDateTime": "2026-03-14T18:21:09Z",
"controlState": "FAIL",
"failureReason": "TICKET_ALREADY_USED",
"flow": "IN",
"externalControlIdentifier": "20260314-GATE-A"
}
]
| Field | Required | Meaning |
|---|---|---|
barcode | yes | The barcode scanned — the one received in the export. |
controlDateTime | yes | When the ticket was scanned, with its time zone offset. |
controlState | yes | OK, FAIL, OFFLINE_OK or OFFLINE_FAIL (the OFFLINE_* values for scans a device made while disconnected from your system). |
externalControlIdentifier | yes | Identifier of the control session in your system. A timestamp is fine when you have nothing better. |
failureReason | no | Why the ticket was refused, e.g. TICKET_ALREADY_USED, TICKET_ON_BLACKLIST, TICKET_NOT_VALID_TODAY, WRONG_ARTICLE, INVALID_TICKET. |
flow | no | IN (default) or OUT, for venues that control exits and re-entries. |
gateCode, sectorCode, deviceCode, additionalInfo | no | Where and by what the ticket was scanned — used by reporting and venue filling. |
Good practice:
- Send the scans continuously, in small batches, at the same rhythm as the export (every 30 to 60 seconds on event day). That is what makes venue filling and the TIXNGO app live.
- A batch is recorded whole or not at all. On a
400, fix or drop the faulty check and resend; if you need to know exactly which check is refused, send them one by one. - Scans collected offline are sent when connectivity comes back, with their original
controlDateTimeand anOFFLINE_*state.
Related Documentation
- Authentication & Authorization — How to obtain and manage OAuth 2.0 tokens
- Export Ticket List API Reference — Full API specification for ticket list extraction
- Reset Ticket List Export API Reference — Restart an export from the beginning
- Import Ticket Checks API Reference — Full API specification for scan result reporting
- List Seasons, List Events, List Competitions, List Visit Passes — Where to find the ids of the export scope
- Rate Limits — API performance and rate limit guidelines