layout: documentation-partner-api categories:

excerpt: The Ticketmaster Partner API lets clients reserve, purchase, and retrieve ticket and event information.

Ticketmaster SafeTix

Partners who are selling events powered by Ticketmaster SafeTix and authorized to fulfill the tickets for fans will receive an encrypted token from the Order Management API. Ticketmaster SafeTix is a new technology that reduces the risk of ticket fraud from stolen or illegal counterfeit tickets, provides event owners with greater control over their tickets and visibility into the individual fans who attend their events.

After receiving the encrypted token from the Order Management API, partners will need to pass the token to the Ticketmaster Secure Entry SDK to render the tickets within their app. To learn more about Ticketmaster SafeTix click here.

Partners will need to perform the following steps to integrate SafeTix:

  1. Integrate with Secure Entry SDK (iOS, Android, JavaScript) within your mobile web or app experience
  2. Pass a partner account ID for each unique user during checkout to associate the tickets with a partner account. (Partners should reuse the same account ID for each user).
  3. Call Order Management endpoint to retrieve the SafeTix Rotating Entry Token (RET) encrypted token
  4. Continue to generate mobile and PDF tickets for non-Ticketmaster SafeTix events

Partner API Integration:

Overview

  1. Identify SafeTix enabled/enforced events.
  2. Create a Host order including the Third-party account ID. (the unique account ID associated with the fans account in your system)
  3. Call Order Management API to get the order info and SafeTix (RET) encrypted token.
  4. Render the SafeTix encrypted token via the Secure Entry SDK. (Note: this will be a direct integration with Secure Entry SDK).
  5. Call Secure Render API to Refresh the Encrypted Token.

NOTE: Partners will need to refresh the token 20 hours prior to the start of the event and whenever the ticket is displayed in your app.

1] Identify SafeTix enabled/enforced events

  1. Availability API response contains a SafeTix Enabled Flag (“safeTixEnabled”) to identify the events.

2] Create Host Order

While creating a Host order

  1. In the add billing step include the Third-Party account ID in the request body (see the request below).
  2. Commit the cart after add billing step is successful.

NOTE : Please note that the third_party_account_id sent in this step will be required to be sent as header x-user-id when making a call to refresh the token.

Add Billing Request [PUT]

Request Response

https://app.ticketmaster.com/partners/v1/events/0B004D43F86C478F/cart/payment?apikey=GkB8Z037ZfqbLCNtZViAgrEegbsrZ6Ne

{ 
   "cartId":"4f215dbf-e911-498a-a51e-ca9b584c2731",
   "payment":{ 
      "first_name":"Tom",
      "last_name":"Brown",
      "home_phone":"4110001234",
      "type":"BRAINTREE",
      "reference":"",
      "address":{ 
         "line1":"123 Main Street",
         "line2":"",
         "unit":"1",
         "city":"Hollywood",
         "country":{ 
            "code":"US",
            "id":"840"
         },
         "region":{ 
            "abbrev":"CA"
         },
         "postal_code":"92806"
      },
      "amount":"54.41",
      "currency":"USD",
      "card":{ 
         "number":"fake-valid-visa-nonce",
         "cin":"123",
         "expire_month":0,
         "expire_year":0
      },
      "email_address":"tom.brown@email.com",
      "third_party_account_id":"12313131"
   }
}
{
"cart_id": "beec42c9-f456-4270-bba9-4c62528bef00",
"cart": {
  "items": [
    {
      "type": "ticket",
      "id": 1,
      "areas": [
        {
          "description": "Second Balcony",
          "id": 8
        },
        {
          "description": "Left Side of Theatre",
          "id": 9
        },
        {
          "description": "Seats are Odd-Numbered",
          "id": 11
        },
        {
          "description": "Price Level 7",
          "id": 16
        }
      ],
      "tickets": [
        {
          "description": "Standard Ticket",
          "id": "000000000001",
          "quantity": 1,
          "inventory_type": "PRIMARY",
          "charges": [
            {
              "price": 0.00,
              "type": "distance",
              "quantity": 1,
              "tax": 0.00
            },
            {
              "price": 0.00,
              "type": "facility",
              "quantity": 1,
              "tax": 0.00
            },
            {
              "price": 57.00,
              "type": "face_value",
              "quantity": 1,
              "tax": 4.13
            },
            {
              "price": 34.20,
              "type": "service",
              "quantity": 1,
              "tax": 2.57
            }
          ]
        }
      ],
      "ga": false,
      "totals": {
        "currency_code": "USD",
        "fee": 34.20,
        "grand": 97.90,
        "merchandise": 57.00,
        "tax": 6.70
      },
      "event_id": "3F005105D843DFA3",
      "num_seats": 1,
      "x-num": 28,
      "row": "B",
      "section": "BALC2L",
      "start_seat_number": "13",
      "end_seat_number": "13",
      "is_ga": false
    },
    {
      "type": "processing",
      "id": 2,
      "totals": {
        "currency_code": "USD",
        "fee": 3.76,
        "grand": 3.76,
        "merchandise": 0.00,
        "tax": 0.00
      }
    },
    {
      "type": "delivery",
      "id": 4,
      "totals": {
        "currency_code": "USD",
        "fee": 0.00,
        "grand": 0.00,
        "merchandise": 0.00,
        "tax": 0.00
      },
      "carrier": "TICKETMASTER",
      "service_level": "ETICKET",
      "description": {
        "long": "Get in with:",
        "short": "eTickets",
        "eta": "eTickets"
      },
      "requires_address": false
    }
  ],
  "totals": {
    "currency_code": "USD",
    "delivery": 0.00,
    "fee": 37.96,
    "grand": 101.66,
    "merchandise": 57.00,
    "tax": 6.70,
    "unpaid": 0.00,
    "upsell": 0.00
  },
  "payments": [
    {
      "id": 1,
      "payment_id": "1",
      "type": "CC",
      "amount": 101.66,
      "card": {
        "expire_month": 12,
        "expire_year": 2020,
        "issuer": "VISA",
        "number": "******************2474"
      }
    }
  ],
  "hold_time": 444
}
}

3] Call Order Management for Initial Encrypted Token

Call Order Management API to get the order info and the initial SafeTix encrypted token. This will be POST request and will include a request body with the following structure.

Order Management Request [POST]  

/partners/v1/orders?order_token={order_token}&apikey={apikey}

Request Structure:

Field Char limit Data type Required Description
device_id max 50 characters string Y The device ID passed in the request
device_type max 20 characters string Y Acceptable Values: web, native
device_os max 50 characters string Y Acceptable Values: ios, android, other
third_party_account_id max 100 characters string Y The third party account id passed when adding billing.

Request

{
    "device_id":"12345",
    "device_os":"android",
    "device_type":"web",
    "third_party_account_id":"12313131"
}

Order Management Response: When Delay Delivery Ticketing ON

Order Management Response with “Delay Ticketing” information When Delay Delivery is ON, the Order Management response includes the date in the ‘additional_info’ value when the secure entry token can be retrieved. Partners need to parse the value and message ticket buyer the date the secure entry token can be retrieved.

Response

{
  "third_party_source": "abc.com",
  "options": [
    {
      "option_number": 11,
      "description": "ACCOUNT MODIFIED"
    }
  ],
  "delivery": {
    "carrier": "USPS",
    "service_level": "SAFETIX",
    "description": {
      "short": "SafeTix Rotating Entry Token"
    }
  },
  "tickets": [
    {
      "barcode_id": "1212121212121212",
      "display_id": "39-20827/PHX",
      "event_code": "ECAPI1",
      "event_host": "PHX",
      "event_id": "3F005105D843DFA3",
      "is_ga": false,
      "is_national_vip": false,
      "order_date": "2019-12-05",
      "order_number": "39-20827/PHX",
      "portal": "SECOND BALCONY",
      "row": "K",
      "seat_id": "50528288",
      "seat_name": "104",
      "section": "BALC2",
      "voided": false,
      "charges": [
        {
          "description": "Price",
          "sub_type": "price",
          "type": "price",
          "amount": {
            "amount": 37.00,
            "currency": "USD"
          }
        },
        {
          "description": "Distance Charge",
          "sub_type": "distance_charge",
          "type": "fee",
          "amount": {
            "amount": 0.00,
            "currency": "USD"
          }
        },
        {
          "description": "Facility Charge",
          "sub_type": "facility_charge",
          "type": "fee",
          "amount": {
            "amount": 0.00,
            "currency": "USD"
          }
        },
        {
          "description": "Service Charge",
          "sub_type": "service_charge",
          "type": "fee",
          "amount": {
            "amount": 0.00,
            "currency": "USD"
          }
        },
        {
          "description": "Tax",
          "sub_type": "tax",
          "type": "tax",
          "amount": {
            "amount": 5.26,
            "currency": "USD"
          }
        }
      ],
      "secure_entry_data": {
        "render_type": "rotating_symbology",
        "segment_type": "ROTATING_SYMBOLOGY",
        "token": "xxxxxBVRytNDM2NzkzODA2NDAwMTUwMSIsInQiOiJBMEZeyJiIjoiUFBQUFRQUvQjlDIiwiY2siOiJjY2M3YTdkYjI4OTEzNDFjNzA1MmVmOWJmOWZhMThkYTNkOWN4IM2MGU2YzFjIiwicnQiOiJyb3RiwiZWsiOiJmM2I5ODhdGluZ19zeWxvZ3kifQTGIyZpbEZlYzAwNDY1NGE0NDUyMzljNGZlYTgzNGQyNmhtSUNFWkVFBQUJhdWs4WVpLV2sGQEREVxdHg5ZVdm=="
      }
    }
  ],
  "voided": false,
  "additional_info": {
    "safetix_delivery_delay_date": "2020-04-05"
  },
  "device_id": "12345",
  "device_type": "web",
  "device_os": "android",
  "nfc_capable_device": false,
  "third_party_account_id": "12313131",
  "tm_sends_redemption_claim_email": false
}

Order Management Response: When Delay Delivery Ticketing OFF

When Delay Delivery is OFF the Order Management response includes the Secure Entry Token.

Response Structure Secure Entry Data :

Secure Entry Data

Field Data type Required Description
token string Y TBase64 Encoded (SecureTokenObject)
render_type string Y Indicates the type of symbology that will be rendered: “rotating_symbology” – PDF417 Rotating Token with QR Code Fallback OR “barcode” – QR Code only
segment_type string Y Indicates the type of segment
error Object N Additional error codes if available

Error

Field Data type Required Description
code integer Y secureRender status code
message string Y Additional information and textual description.

Response

{
  "customer_email": "raine.cabal@ticketmaster.com",
  "third_party_source": "BiT (QA)",
  "delivery": {
    "carrier": "TICKETMASTER",
    "service_level": "SAFETIX",
    "description": {
      "short": "SafeTix Rotating Entry Token"
    }
  },
  "tickets": [
    {
      "barcode_id": "",
      "display_id": "39-20804/PHX",
      "event_code": "ECAPI1",
      "event_host": "PHX",
      "event_id": "3F005105D843DFA3",
      "is_ga": false,
      "is_national_vip": false,
      "order_date": "2019-11-27",
      "order_number": "39-20804/PHX",
      "portal": "SECOND BALCONY",
      "row": "B",
      "seat_id": "67174428",
      "seat_name": "9",
      "section": "BALC2L",
      "voided": false,
      "charges": [
        {
          "description": "Price",
          "sub_type": "price",
          "type": "price",
          "amount": {
            "amount": 57.00,
            "currency": "USD"
          }
        },
        {
          "description": "Distance Charge",
          "sub_type": "distance_charge",
          "type": "fee",
          "amount": {
            "amount": 0.00,
            "currency": "USD"
          }
        },
        {
          "description": "Facility Charge",
          "sub_type": "facility_charge",
          "type": "fee",
          "amount": {
            "amount": 0.00,
            "currency": "USD"
          }
        },
        {
          "description": "Service Charge",
          "sub_type": "service_charge",
          "type": "fee",
          "amount": {
            "amount": 34.20,
            "currency": "USD"
          }
        },
        {
          "description": "Tax",
          "sub_type": "tax",
          "type": "tax",
          "amount": {
            "amount": 6.70,
            "currency": "USD"
          }
        }
      ],
      "secure_entry_data": {
        "render_type": "rotating_symbology",
        "segment_type": "NFC_ROTATING_SYMBOLOGY",
        "token": "eyJiIjoiMDExODg1NjY5ODg2NTM5NiIsInQiOiJCQVVBTDR6bHR5SDJFUUlBQUFBQUFRQUFBQUIraHBYTThsQnpwQWxvVEdKVldZZDB2amxSdmpta2FMTm4rK1FiIiwiY2siOiI5NWQxY2VmZThkOGNhOWZkMTQyOGMyOTM5ODg4MDFjNmYzOGM5MzYwIiwiZWsiOiI1ZGUxMzY3MDYzODAwMWZhN2RjOGE2NDdjMjA3ZGMzNDlkMDRkMWM3IiwicnQiOiJyb3RhdGluZ19zeW1ib2xvZ3kifQ=="
      }
    }
  ],
  "voided": false,
  "additional_info": {
    "safetix_delivery_delay_date": "2020-04-05"
  },
  "device_id": "12345",
  "device_type": "NATIVE",
  "device_os": "IOS",
  "nfc_capable_device": true,
  "third_party_account_id": "12313131"
}

4] Render the SafeTix encrypted token via the Secure Entry SDK

Overview:

  1. Pass Token to the Secure Entry SDK to render the Rotating Barcode

This integration applies to all digital tickets events that are enabled for SafeTix. The API will determine the event configuration, create the right token, and the SDK’s will render the correct barcode.

Secure Entry SDKs

  1. iOS: https://github.com/ticketmaster/iOS-SecureEntrySDK
  2. Android: https://github.com/ticketmaster/Android-SecureEntrySDK
  3. JavaScript: https://github.com/ticketmaster/JavaScript-SecureEntrySDK

NOTE :

drawing

5] Call Secure Render API to Refresh the Encrypted Token

Call Secure Render API and populate with the following required fields in the request structure:

Note :

/marketplace/v1/securerender?apikey=YourAPIKey

Note : Please use POST /marketplace-staging/v1/securerender?apikey=YourAPIKey — For preprod environment

Request Structure:

Request Response

POST https://app.ticketmaster.com/marketplace/v1/securerender?apikey=YourAPIKey
-H 'Content-Type: application/json'
-H 'x-user-id: 783412345'

{
  "deviceId": "68753A11-1234-1226-9D60-0050E4C000000",
  "deviceType": "NATIVE",
  "deviceOs": "IOS",
  "userAgent": "Mozilla/5.0",
  "tickets": [
    {
      "eventId": "3F005237E5CB39EA",
      "section": "G",
      "row": "17",
      "seat": "1",
      "barcode": "964537283421"
    },
    {
      "eventId": "3F005237E5CB39EA",
      "section": "G",
      "row": "17",
      "seat": "2",
      "barcode": "963267823784"
    }
  ]
}
200 OK Response Example:

{
 "deviceId": "68753A11-1234-1226-9D60-0050E4C000000",
 "deviceType": "NATIVE",
 "deviceOs": "IOS",
 "nfcCapableDevice": true,
 "tickets": [
    {
    "eventId": "3F005237E5CB39EA",
    "section": "G",
    "row": "17",
    "seat": "1",
    "barcode": "964537283421",
    "token": "eyJiIjoiMDg2NzM0NjQ3NjA0MTYxNmEiLCJ0IjoiQkFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFDR2tmNWxkZWZ3WEh3WmpvRmMzcnNEY0RINkpyY2pqOW0yS0liKyIsImNrIjoiNjhhZjY5YTQtZjlhNi00ZTRhLTkxZmEtNDYwYmRhMTdmNDI3IiwiZWsiOiIwNmVjNTNjNy00OWU0LTQ3YTQtODgwMi01N2Y3M2RjM2FiZmMiLCJydCI6InJvdGF0aW5nX3N5bWJvbG9neSJ9",
    "renderType": "rotating_symbology",
     "passData": {
        "ios": {
          "pkPassId": "b5d02b52-4b21-4233-b41a-722f20467535"
        }
      }
    }
  ]
}

400 BAD REQUEST Response Example:

{
  "deviceId": "68753A11-1234-1226-9D60-0050E4C000000",
  "deviceType": "NATIVE",
  "deviceOs": "IOS",
  "nfcCapableDevice": false,
  "tickets": [
    {
    "eventId": "3F005237E5CB39EA",
    "section": "G",
    "seat": "1",
    "barcode": "964537283421",
    "error": {
        "code": 400,
       "error": "missing.row.attribute"
      }
    }
  ]
}

Basic Flow Overview

1. GET /partners/v1/events/{event_id}/availability

2. POST /partners/v1/events/{event_id}/cart

3. PUT /partners/v1/events/{event_id}/cart/payment — This requires one additional field in the request body “third_party_account_id”:”12313131”. (when you send us the billing information you must also pass a unique user id.)

4. PUT /partners/v1/events/{event_id}/cart

5. POST /partners/v1/orders?order_token={order_token}&apikey={apikey} — To get the Initial SafeTix token

6. POST /marketplace/v1/securerender?apikey=YourAPIKey — To refresh the token

Important Notes:

 1. The header `x-user-id` sent in this step should be same as the `third_party_account_id` sent when adding billing.
 2. Please use POST /marketplace-staging/v1/securerender?apikey=YourAPIKey  --- For preprod environment

FAQ

1. How often must the token be refreshed? You should refresh the token anytime a fan opens and views a ticket within your app and 20 hours prior to the event. If you are unable to refresh the token when the fan views the ticket at the gate, then the SDK would attempt to use the token refreshed 20 hours prior. The token should still be valid. You do not need to refresh the token every 20 hours.

2. Why do we need the barcode for SafeTix events? The barcode is a required parameter for the SecureRender API. The barcode is returned in the* Order Management API* response. The barcode is used to determine if a valid ticket has been created before it generates the token. Partners are required to call Secure RenderAPI to refresh the SafeTix token and you pass the barcode in the request. The numerical value of the barcode does not change, the tokens changes.

3. What is the Device ID? This is a unique identifier specific to that device/app install. If you can’t get the hardware number, then you should send a unique identifier from that app on that specific device. It can be a GUID that is sticky to that app install. The deviceId must be unique which helps Ticketmaster better combat fraud and improve security. An order-uuid while unique will not help us differentiate the devices enough as a user who has two devices and two applications installed would give us the same deviceId. This will not work for our SafeTix system.

4. What if the user changes their phone or device? If a user changes the phone or device after receiving the barcode, you should send the device ID for the new phone or device.

5. How do you know when the event is SafeTix? Use the Order Management API response as your signal to determine when an event is using SafeTix. If you get a token, then you know the event is using SafeTix, and you should always use the SDK to display the token and the SecureRender API to refresh it. If you only get a barcode (without a token), then you know the event is not using SafeTix, and you can render a QR code.

6. What if the fan purchases a new phone in between ticket order and ticket redemption? We fully expect and anticipated this behavior. The Device ID you pass for the initial purchase can be different from the id you pass for refresh/redemption. The system supports this behavior.

7. Are partners required to use the Secure Render SDK to render the barcode? Yes. We recommend partner integrators to use the TM Secure Render SDKs since that will avoid any inconsistency issue with rendering and scanning.

8. What is the SLA for the Order Management API and Token Refresh? 1. Order Management: 800ms +/- with 99.50% uptime 2. Token Refresh: 500ms +/- with 99.99% uptime

9. Is there any recommended sizing for SafeTix barcodes?

drawing