These docs are new as of August 2012 with the release of Version 9 of our API. We will be deprecating V8 in the near future but will be sure to give you sufficient notice before we do so. Sign up below to receive API updates from us.

Receive updates on changes to our API
* indicates required

The Exchange API enables developers to write their own tools to search existing ticketpplic inventory, manage their own inventory, and create orders.

REST

The web service is based on Representational State Transfer, or REST. This simply means that each resource can be referenced by its own URL, and the actions performed on that resource correspond to HTTP methods. For instance, to fetch data you would issue a GET request for the desired resource with any options specified as query parameters.

POST is used to create resources, PUT to update them, and DELETE for removal. POST and PUT requests usually have a request body to specify the contents of the resource that should be created or updated. In this case, the request body should be passed as JSON that closely matches the response format, although not all attributes will necessarily need to be specified.

Generally speaking, HTTP status codes are used appropriately for each response. For instance, 422 Unprocessable Entity is given when validation fails for the given input.

The response format given by the web service is JSON, which is a lightweight data-interchange format. It's a simpler format than XML that also has the advantage of being used directly by the browsers' JavaScript implementations.

Environments

There are two distinct environments available for the API. The production environment is the one your production applications should use, but a sandbox environment is also provided for testing your integrations. The sandbox is an environment completely isolated from production, but some of its data is based on the data from the production environment.

Authentication credentials (your token and secret) are enabled on either sandbox, or production, but not both.

The following are the hostnames that should be used for each environment.

Production
api.ticketevolution.com/v9/
Sandbox
api.sandbox.ticketevolution.com/v9/

It's especially critical that any testing of non-GET requests be done in the sandbox environment to avoid making unintentional or detrimental changes to production data.

Controlling Your API Settings

All of the settings for the API are managed via Ticket Evolution Settings App including: your API credentials, price markup/markdown rules, price rounding rules, featured inventory and removing brokerage offices from your feed. Other than your default overall markups, these settings can be managed per API token giving you maximum flexibility.

Each environment has it’s own Settings App and the settings are specific to that environment only.

Production
https://settings.ticketevolution.com/
Sandbox
https://settings.sandbox.ticketevolution.com/

An account for you to login to the Sandbox is not created for you by default. If you need one created please open a ticket to have one created.

SSL

All requests to the API must be performed over SSL.

While the production endpoint has an SSL certificate signed by a certificate authority (CA), the certificate in use in the sandbox environment is self-signed. This doesn't affect the security of the data being transferred, but keep it in mind if you're trying to verify the certificate.

Authentication

To access the web service, you will need to provide authentication credentials in the form of an access token. This should be specified by passing a header along with each request called X-Token. Not passing this header or passing the header with an invalid API token will result in a 401 Unauthorized response.

You may create and manage your tokens in the Brokerage->API Credentials area of the Ticket Evolution Settings App

Each environment has separate tokens, so be sure to use the appropriate token for the environment or you will receive a 401 Unauthorized response.

Signing

The web service also makes use of request signing for increased security. Signed requests prevent someone from obtaining your API token and using it on your behalf.

To start, you'll need to build your input string.

We used to require that the string-to-be-signed have a question mark regardless of whether there were query string parameters. This is no longer necessary.

GET requests

To start, you'll need to build up a string that includes the request method GET, the host name (e.g. api.ticketevolution.com), the path (e.g. /brokerages), and an optional query string that must be sorted by key (e.g. ?page=1&per_page=1).

Here's what that full string should look like when you put it all together:

GET api.ticketevolution.com/brokerages?page=1&per_page=1

or a request without parameters

GET api.ticketevolution.com/categories?
POST, PUT, DELETE requests

In the case of POST,PUT and DELETE requests when a request body is present, the request body should be used in the source string in lieu of the query string.

POST api.ticketevolution.com/clients?{"clients":[{"name":"Elissa Weimann"}]}
Doing the signing

Use our Signature Test Tool to check if the signatures you're making are correct, and generate cURL requests right in the browser.

Once you've built up the input string as shown above, it should be hashed using HMAC-SHA256 using the secret obtained in the Brokerage management console in the Broker Exchange. In Ruby, this might look like this:

require 'base64'
require 'openssl'

secret = "xyz"
request = "GET api.ticketevolution.com/brokerages?page=1&per_page=1"

digest = OpenSSL::Digest::Digest.new('sha256')
signature = Base64.encode64(OpenSSL::HMAC.digest(digest, secret, request)).chomp

puts signature # => "ohGcFIHF3vg75A8Kpg42LNxuQpQZJsTBKv8xnZASzu0="`

This hashed string should then be passed in the X-Signature header. If the secret were xyz, this would look like X-Signature: ohGcFIHF3vg75A8Kpg42LNxuQpQZJsTBKv8xnZASzu0=. A curl request might look like this:

curl -i \
  -H Accept: application/vnd.ticketevolution.api+json; version=8 \
  -H X-Signature: ohGcFIHF3vg75A8Kpg42LNxuQpQZJsTBKv8xnZASzu0= \
  -H X-Token: abc \
  -X GET
  'http://api.ticketevolution.com/brokerages?page=1&per_page=1'

If you're having trouble and getting 401 responses back from your requests, please use the Signature Test Tool to make sure you're generating a valid signature.

Versioning

In order to provide a clear path for future changes, the web service is versioned. Each request must include an Accept header. The current web service version is 8, so this header would be Accept: application/vnd.ticketevolution.api+json; version=8. Specifying an invalid version number will result in a 406 Not Acceptable response.

Conditions

Additional conditions may be passed as query parameters. The following parameters will let you change the result set size for the list endpoints and access additional pages.

  • per_page - defaults to 100, maximum of 100
  • page - defaults to 1

Some endpoints also have additional parameters as documented below.

If you don't know the exact value, you can use the following modifier suffixes in your queries by appending them to the parameter name.

  • eq - equal (case-sensitive)
  • not_eq - not equal (case-sensitive)
  • gt - greater than
  • gte - greater than or equal
  • lt - less than
  • lte - less than or equal

For example, this query would find all of the events occurring between May 15 and May 20, 2011:

/events?occurs_at.gte=2011-05-15&occurs_at.lt=2011-05-20

Rate Limit

In order to provide a consistent level of performance for all of our customers, an API request rate limit of 36,000 requests/hour is in place. This is a generous limit, so please don't abuse it. If the rate limit is exceeded, a 503 status will be returned, with the following response body.

{"error":"Rate Limit Exceeded"}

E-Tickets

All E-Ticket attributes are stored on items for each order. You can download E-tickets or Upload E-Tickets via the API.

The following attributes are returned on the Order List and Show actions:

  • eticket_delivery - Boolean shows you whether that particular item is an E-Ticket
  • eticket_available - Boolean shows whether or not the E-Tickets have been uploaded
  • eticket_downloaded_at - The DateTime in UTC that the E-Tickets were last downloaded at
  • eticket_downloaded_by - IP address of the user that last downloaded these E-Tickets

To upload E-Tickets for Orders use this endpoint.

To download E-Tickets for Orders use this endpoint.