Archtics Season Ticketing API

Archtics Season Ticketing API Specification

Overview

The Archtics 3rd-party Application Programming Interface (API), known as Archtics Transaction Services (ATS) is an Internet-facing request/response Web service that provides access to a broad array of information in an Archtics database. This is a collection of API calls that are used by external systems to access season ticketing data. This API system communicates over HTTPS and uses JSON command syntax. Each API call is a POST call and each call is intended to access data from a specific client. The contents of the JSON payload contain the desired read or write operation. There are over one hundred APIs supporting access to Archtics that can be categorized in the the groups listed below:

ADMINISTRATIVE - This group of calls includes a basic ‘ping’ call and calls to discover system data (ticket types, classes) that are used to support other API calls.

ACCOUNT MANAGEMENT - This group includes calls to query, create and update Archtics accounts (customer attributes include name, address, email, etc) - calls which can be used to create and synchronize external copies of accounts. The group also includes calls to discover seats/tickets sold to a specific account (plan or event). Most calls are read-only calls, although the system provides limited ability to update records (add/update customer). These calls are typically used for Customer Relationship Management (CRM), client portal, and mobile applications.

DISCOVERY – These calls allow callers to discover attributes about Archtics events, including team/performer, venue, date/time, pricing, availability, sales, and more. These read-only calls are typically used for client portals and dashboards, mobile apps, and in support of ticket purchase implementations.

EVENT EXPERIENCE – This group of calls provides seat-level information related to day-of-game activities, including attendance scan history (useful in near-realtime ingress dashboards or instant messaging to seat holders). Calls are available to support ticket added/loaded monetary value on a ticket. Clients can associate monetary (defined dollar amount) or non-monetary (pizza and a coke, food/beverage discount) value to a customer’s ticket, which is redeemable upon presentation of the ticket to a Point of Sale vendor.

TICKET PURCHASE – After discovering available inventory and pricing, these API calls allow the caller to hold, reserve and purchase tickets for an event. The system supports the selection of best-available or specific seats. Integrators can use either the client’s or an external credit card authorization system. Use of on-line and off-line payment methods are supported. These API calls support new and incremental sales, seat upgrades or exchanges, ticket repricing, and return of previously-purchased seats. Use of these Ticket Purchase API calls requires approval from the Ticketmaster and from the client/team.

Major Functional API Groups

ADMINISTRATIVE

• ping – confirms connectivity to the database; discover system availability and performance information
• service_charge_details – provides all eligible services charges and delivery charges in the database.
• system_options – provides system-level data about classes, payment methods, ticket types, account-groups, and ticket delivery methods.

ACCOUNT MANAGEMENT (includes customer attributes, seats on accounts)

• get_accounts_with_updates – provides a list of accounts that have been updated since a specified date/time.
• customer_add – allows caller to create a new customer account; email address must be unique in the database.
• customer_query – allows caller to determine whether a customer exists in the database; email address or account ID is a required input parameter.
• customer_update – allows caller to update specific information on a customer’s account.
• get_accounts_with_sales – provides a list of customer accounts accounts with sales since a specific date/time.
• get_acct_rep – provides Account Representative names for a customer account
• get_event_price_code_updates - provides a distinct list of events and price codes that have been added or updated since a specific date/time
• get_seats_on_account – provides information about each seat on an account; this API call provides less data than “seats_sold”
• get_seats_on_account_reserved - provides information about each seat that is reserved (not sold) to an account;
• get_sth_status – allows a caller to discover whether or not the account holder owns one or more tickets to a plan in an item set. This is used to determine whether a consumer is a Season Ticket Holder (defined by the client).
• seats_sold – provides detailed information about seats currently owned by a customer account. This can be filtered by a specific event, item-set, section, etc.
• update_acct_memo – allows a caller to Update an existing Archtics note or memo.
• verify_ticket_in_item_set - allows a caller to discover whether or not the account holder owns one or more tickets to a plan or an event. This is similar to get_sth_status.

DISCOVERY (includes sales, inventory, pricing, events, availability)

• event_details – discover event attributes, including event name, date, time, opponent, etc.
• event_price_info – discover pricing information for a specified event
• event_search - discover a list of events during the next N days; can be limited to events in an item set.
• get_avail_seats – discover available seating inventory for a specific event.
• get_event_manifest – discover all sections, rows, and seats for a specified event. This can be used with seat-map displays.
• get_events_with_sales – provides a list of events that have had sales since a specified date and time.
• get_ticket_sales – Discover ticket sales and returns that have occurred since a specified date for an event or item set.

EVENT EXPERIENCE (includes attendance, loaded value)

• get_attendance – provides attendance data for an account, an event, or a combination of account and event.
• get_attendance_incremental - provides all entry scans since a specified date/time.
• get_av_barcodes – provides any added (loaded) value on a ticket.
• verify_barcode – provides the account, seat location and pricing details associated with a specified barcode.

=== See detailed API call syntax and samples for several common calls below ===

Access

Initial self-service access to a few selected ‘starter’ API calls such as account query and event discovery against a test database is available to anyone after obtaining their API key. Access to the rich set of APIs, and eventually access to client production data, is available by joining Ticketmaster’s ‘Nexus’ partner program. Access to production systems, including the specific set of API calls allowed, and access to specific Archtics client databases is governed by the business relationship between Ticketmaster, our clients, and our partners. Clients performing their own ‘self-integration’, as opposed to using a 3rd-party solution, are supported via the same technical solution.

Get your API key

• Login here to get your API key.
• On the Login screen, login if you have an existing account, or click “Create new account” button.
• Fill out the form if you are creating a new account, using the name and email address of a contact person in your organization. Ticketmaster will contact you by this email address if you wish to become a Ticketmaster partner. Recommendation - use your company’s name or email domain name as your username.
• If you create a new account, you will receive a welcome message in your email with further instructions. Follow the instructions to login to Ticketmaster Developer Center and set your password. Logout when your password has been saved and then login again.
• The system will create an App for you (the App name = {username}-app).
• Click on the App name to reveal your Customer Key (this is your unique APIKEY).
• Congratulations! You are ready to make API calls to our sample Season Ticket database.
• See samples below of the read-only calls that can be made for testing purposes.

How to Construct the URL

URL format: HTTPS://app.ticketmaster.com/{product}/{resource}?dsn={dsn}

In the header the APIKEY is needed, please add apikey= {apikey}

Test your API calls:

• Use any Rest Client (e.g., Google ARC, Postman, Insomnia, JetBrain, Cocoa) for testing the API calls. Configure the REST client as follows:
• Construct an API call (see samples below)
• The caller (or calling application) will:
  • POST a JSON call to: https://app.ticketmaster.com/sth-customer/ticketing_services.aspx?dsn=apigee
    • use HTTPS protocol
    • specify the product (sth-customer)
    • specify the DSN (apigee)
    • specify your unique API Key in the header
• Continue to poll until the request is complete OR until the time-out value is reached (see instructions for Asynchronous Polling, below)
• The application will:
  • Confirm the validity of the caller’s API key
  • Confirm that the API Key has access to the requested DSN
  • Compare the DSN in the URL with the DSN in the JSON payload
  • Confirm that the caller has not exceeded any established rate limits
    • Current limits are 80 calls per minute or 5000 calls per day
  • Direct the JSON request to the appropriate Ticketmaster database
  • Return the JSON response to the call.
• A rapid response can be expected for each of the sample API calls below, except ATS_EXT_TEST_POLLING.

API Call Samples by Functional Grouping

ADMINISTRATIVE GROUP

PING

Purpose: Confirms system connectivity and server status.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd": "ping",
        "call_reason": "test",
        "uid": "user99",
        "dsn": "apigee"
    }
}

ATS_EXT_TEST_POLLING

Purpose: Allows caller to test the asynchronous polling method by introducing a 10-second delay in the response. You can make this API call, receive a “202 Accepted” response with the CTKN cookie, and continue making the call until you receive a “200 OK” response. See the section on Asynchronous Polling, below.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd": "ats_ext_test_polling",
        "uid": "user99",
        "dsn": "apigee"
    }
}

ACCOUNT MANAGEMENT GROUP

CUSTOMER_QUERY

Purpose: Returns basic account and name information based on an input account-id, email address or external-id.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd": "customer_query",
        "ref": "optional-reference",
        "uid": "user99",
        "dsn":"apigee",
        "site_name": "vanilla",
        "acct_id": 100479,
        "call_reason": "S"
    }
}

SEATS_SOLD

Purpose: Retrieves detailed information about seats that are sold to a consumer’s account.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name":"testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd":"seats_sold",
        "uid": "user99",
        "dsn":"apigee",
        "acct_id": 100479
    }
}

DISCOVERY GROUP

EVENT_SEARCH

Purpose: Returns attributes about events that occur within a specified date range.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "v999"
    },
    "command1": {
        "cmd": "event_search",
        "ref": "1AB2C3",
        "uid": "user99",
        "dsn": "apigee",
        "check_availability": "N",
        "start_date": "2016-10-01",
        "end_date": "2016-12-31"
    }
}

EVENT_DETAILS

Purpose: Returns a list of events and event attributes.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd": "event_details",
        "event_filter": "EVENT01,EVENT02",
        "event_filter_type": "L",
        "uid": "user99",
        "dsn": "apigee"
    }
}

EVENT EXPERIENCE GROUP

GET_ATTENDANCE

Purpose: This API call returns attendance data for an account, an event or a combination of an account and event.

{
    "header": {
        "ver": 1,
        "src_sys_type": 2,
        "src_sys_name": "testing",
        "archtics_version": "V999"
    },
    "command1": {
        "cmd": "get_attendance",
        "ref": "testing",
        "uid": "user99",
        "dsn": "apigee",
        "page": "0",
        "event_name": "EVENT01"
    }
}

Asynchronous Polling

Ticketmaster systems support multiple clients and our Web Services layer requires the use of an asynchronous polling method. Here is how asynchronous request processing works:

• Step 1 - Initial call: The caller makes a HTTPS request.
  • Header:
    • HTTP Method = POST
    • Content-Type: application/json
  • Body:
    • The JSON Command should be included here
• Step 2 - Initial response: X seconds later (X is usually < 2 seconds), the server will return a response:
  • If HTTP response "200 OK" is returned
    • Request is complete - no polling logic is required; skip this entire section.
  • If HTTP response "202 Accepted" is returned, the response will include:
    • Set-Cookie: QTKN=<something>
    • Continue to step 3
  • If HTTP response is neither 200 nor 202, contact Ticketmaster for assistance.
• Step 3 - Y seconds later (Y is normally about 500 ms), the caller repeats the initial HTTPS request, using all the "cookies" provided, to check if the response is complete.
  • The entire JSON Command must be included each time the call is re-submitted.
  • Cookie values that were returned by the SERVER with the "Set_Cookie" responses (above) must be provided in this polling step.
    • SID - should not change for the duration of this API polling cycle.
    • BID - should not change for the duration of this API polling cycle.
    • QTKN - use the value provided by the web service in step 2
• Steps 2 and 3 are repeated until response is complete.
• When the response is complete, the server responds with a “200 OK” HTTP header response, and the results of the initial request.
• Ticketmaster recommends setting a timeout value of approximately 2-3 minutes. In other words, continue polling for a response to the same API call for up to 2-3 minutes. If the response for a single API request is not complete within that time, please contact Ticketmaster for resolution. You may also see an error message stating “No data for token ‘{SID}’…”
• Supporting Cookies - If the response contains “Set-Cookie”, the Caller is required to honor those cookies in order to properly use the asynchronous polling method. For example, calling servers should create an HTTP session for each user (caller), and reuse the same HTTP session for the duration of that user session (the duration of that particular API call).

HTTP Result Codes and Meaning

• 200 OK - Successful Query Results
• 202 ACCEPTED - The query was submitted to the Queue server, but response is not yet available; the same query should be tried again soon
• 401 UNAUTHORIZED – Not authorized for this area, or wrong API KEY
• 404 NOT FOUND – Setup issue. Please contact Ticketmaster
• 429 TOO MANY REQUESTS – You have exceeded your quota or rate limit
• 503 SERVICE UNAVAILABLE – Ticketmaster server is currently unavailable

For additional information, please contact Nexus_CPP@ticketmaster.com during business hours (Monday thru Friday from 8AM to 8PM Eastern US).