Presence API
The Ticketmaster Presence API allows you to validate tickets and manage scanning devices for Ticketmaster events.
Overview
Presence API Services
- Configure Scanning Devices
- Validate Ticketmaster Tickets
- Handle Exit and Offline scans
- Pull Configured Scanner Information
Endpoint
All API calls are required to be over SSL and JSON will be used for data interchange.
All development and testing must be performed on the pre-production environment.
Any testing performed in the Production environment should be just exploratory or a smoke test to confirm functionality is deployed correctly. No Load Testing is allowed in the Production environment.
API Flow
Scanner Configuration
Upon startup, the device will need to be configured prior to be able to scan. This will ensure that TM1 Entry can configure the scanner with needed information. The Device Configure Request should be used to configure the device. Once an OKAY status is received back from the Device Configure request, the scanner is ready to scan barcodes.
The device can optionally validate the configuration with the Device Information Request.
If an error or timeout is received from the Device Configuration Request or the Device Information Request, then the scanner is not configured and cannot proceed to scanning barcodes. Upon receiving a timeout, the operation should be resent. If errors are continually received, reach out to Ticketmaster for support.
Scanning
Once configured, the device can now send Entry and Exit scan requests or upload offline scans. The scanner should determine online vs offline mode by whether or not the API endpoint can be reached. If the device is not able to reach the API endpoint (or there is no Internet connectivity), then scanner should proceed in an offline manner. Once the API endpoint can be reached again, the scanner should switch back to online mode.
In the online scanning mode, the scanner must connect to the API endpoint on every scan to register the barcode as entering or exiting. If the request returns anything other than an OKAY status, then the entry/exit of the customer is not allowed. The status returned should be displayed to indicate why the entry/exit was denied.
In the offline scanning mode, the scanner should internally validate the barcode and then save it. When connectivity is restored, the scanner should send back all the saved offline scans with a Ticket Upload Request. Scans should be uploaded with the original scan time stamp and device ID. The system will not reject any of the tickets for being invalid, so the only error will come if the message format is incorrect.
Authentication
All API calls are required to be authorized by using an API Key. Contact your Ticketmaster Nexus Partner Program coordinator to receive an API Key. The API Key needs to be passed as a query parameter in all requests.
Format
All responses are returned in JSON format
Device Service
The Device Service API allows you to configure and manage your scanning devices.
API Device Configure
Configure your scanning device to your venue. This ensures that TM1 Entry and the scanner are in sync and ready for barcode scanning.
API Device Information
Retrieve the information for a configured device. This is not a required call and should only be used to validate that the device is registered
Ticket Service
The Ticket Service API allows you to submit enter and exit scans of Ticketmaster tickets.
External Scanning
For External Scanning the scanner doesn’t require extra configuration and calls to the enter and exit endpoints Presence will assume it is an external gate. By default, the external gates have the following rules:
- The first time a valid ticket is scanned as an entry (using enter endpoint), the ticket will be marked as ENTERED
- Any subsequent enter scans for the same ticket will return as an Already Entered ticket and the access will be denied
- The first Exit scan performed to an already entered ticket will mark the ticket as EXITED
- Any subsequent Exit scans performed to an already exited ticket will return a Exit Not Permitted response.
- Any exit scan to a non-entered ticket will return an Exit Not Permitted response.
Internal Scanning
For Internal Scanning the scanner is required to be assigned to a gate configured for “Internal Scans” rule. The rule has an option to allow multiple entries with the same ticket or to require an exit before allowing the same ticket again. The internal gates have the following rules:
- The first time a valid ticket is scanned as an internal entry it will be added as an internal entry
- if the ticket has not been scanned as an external entry already, the internal entry will also mark the ticket as ENTERED
- The first exit scan performed to an already internal entered ticket will mark the ticket as EXIT INTERNAL
- Any subsequent exit scans performed to an already internal exit ticket will return an Internal Scan Exit not Permitted response
- An internal exit scan to a ticket that has not been internal entered, will return Internal Scan Exit not Permitted
- A gate configured for internal scan will NOT be able to perform external exit scans.
- An internal entry scan from a scanner on a gate not configured for internal scanning will accept the ticket as an Internal Entry
- The /VALIDATE endpoint has been deprecated as of March 2020. Both internal and external entry scans should use enter
API Ticket Enter/Exit
Check the validity of ticket and mark it as entered or exited scanned at an event.
API Ticket Upload
If the scanner can’t connect to the ticket service to validate a barcode online but was given another way to validate it by Ticketmaster, once scanners reconnect to the network and return to an online mode of operation, all offline scans should be sent back to Ticketmaster as soon as possible using the offline scan upload API.
Since scans are being uploaded using the dedicated API endpoint, the TM1 Entry UI will be able to identify the uploaded scans as offline mode in the reports. The upload time will be captured as part of the upload, so only the original scan time needs to be submitted during upload.
F.A.Q.
Q: How do I get the device’s assigned gate id from Presence at device initialization?
A: The Device endpoint will return the gate Id among other information related to the scanner. Please refer to the Device Information section on this page.
Q: Why do I get “NOT FOUND” when the event is not set for today?
A: The barcode is validated against the active events in Presence. If the event is not active, either because it is in the past, or because it is in the future, all barcodes belonging to that event won’t be included in the search domain. An event is active only from the beginning of the scanning period to the end of scanning period.
Q: How do I make the scanners appear on the UI on a specific order?
A: The scanners will appear on the order they are added to the system. If you want the devices to appear on a specific order, you need to add the devices in that order.
Q: How can I scan barcodes when I am off-line?
A: Offline validations should be done only when the scanner is unable to reach out to the ticket service. For more details on how to validate a ticket offline please enter in contact with us.
Q: What is the expected response time for an api call?
A: The response time varies based on the end-point used and the information being sent, on an call to the entry endpoint, if the information is correct and complete. On the ENTRY endpoint, a response of more than 3 seconds should be considered a time-out.
