API Reference (V1)

The Secret Key

Some API calls require your secret key (e.g. when booking a seat).

Important note Never, ever, use this secret key in a script that runs in the browser! It’s a secret key, and must only be used in server-to-server communication and over SSL.

Gzip compression

All seats.io API endpoints can return a payload response that’s compressed with gzip. Compression helps to transport data faster over the network (fewer bytes) and makes frontends respond faster. So in general, it’s a good idea to request gzipped responses.

To do so, send a valid Accept-Encoding header that contains gzip with your request, eg:

    Accept-Encoding: gzip

Note: Some API endpoints always return a gzipped response, even if you don’t explicitly ask for it using the Accept-Encoding response header. This is notably the case for the reporting API endpoints.

Booking and releasing objects

Out of the box, seats.io offers two object statuses: free and booked. The exact meaning of a booked seat depends on your sales process, but this would typically be after the payment has been processed.

There are API calls to /book and /release seats (documentation here).

However, you can also assign other, custom statuses. Say you want to create a separate status ‘reserved’, which indicates that a buyer has selected an object, but payment is not yet complete. That’s where /changeStatus comes into place.

Booking seats, tables or booths

You should use this API call to tell us whenever a ticket sale is confirmed. What ‘confirmed’ means, depends on your sales process, but this would typically be after the payment has been processed.
You can change object status whenever you want. E.g. You could pre-book seats prior to opening up your sales page, to reserve VIP seats.

Note: calling this API will be considered as “booking” for pricing purposes.

To book objects, POST a request to https://app.seats.io/api/book containing the following JSON body:

The request body should look like this:

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

The possible responses are:

You can test this using curl:

curl https://app.seats.io/api/book -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objects': ['A-3','A-5', 'A-7'], 'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Releasing seats, tables or booths

To release objects, POST a request to https://app.seats.io/api/release containing the following JSON body:

The request body should look like this:

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

And the possible responses you can get are:

Test this with the following curl command:

curl https://app.seats.io/api/release -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objects': ['A-3', 'A-5', 'A-7'], 'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Changing status of seats, tables or booths

If you need more statuses than just booked and free, you can use this API call to change the status of a seat, table or booth to your own custom status.

Note: calling this API will be considered as “booking” for pricing purposes.

To do that, POST a request to https://app.seats.io/api/changeStatus containing the following JSON body:

The request body should look like this:

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'status': 'myCustomStatus',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

And possible responses are:

Curl

curl https://app.seats.io/api/changeStatus -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objects': ['A-3', 'A-5', 'A-7'], 'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf', 'status': 'myCustomStatus', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Changing status of general admission areas

The API calls for booking or releasing tickets in general admission areas are slightly different than those for seats. In addition to the ID of the area, you also have to specify a ‘quantity’: the number of tickets to be booked or released.

Note: calling this API will be considered as “booking” for pricing purposes.

POST to https://app.seats.io/api/changeStatus

{
    'objects': [{'objectId': 'GeneralAdmission1', 'quantity': 3}],
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a',
    'status': 'myCustomStatus'
}

Note: here’s the same call in V2.

Booking best available objects

Don’t want ticket buyers to select their seats? That’s possible by passing in bestAvailable when booking objects. Seats.io will automatically book available objects that are closest to the focal point.

The best available seat algorithm

We determine which objects are the best ones as follows:

  1. if seats are available (in the provided categories), we try to book seats closest to the focal point, next to each other on the same row (or table). Also, we make sure no orphan seats are left.
  2. if no consecutive seats are found, or if the requested categories contain other objects than seats, we search for objects closest to the focal point in the same section
  3. if no objects in the same section are found, we search for best available objects over all sections. If there are no sections defined, we search for objects
    closest to the focal point over the whole chart.
  4. if still no objects are found, we throw a 400 - bad request.

How to use it

To book best available seats, send a POST to https://app.seats.io/api/book with the following request body:

{
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a',
    'bestAvailable': {
        number: 2,
        categories: ['balcony', 'stalls'],
        extraData: [{"name": "John Doe"}, {"name": "Jane Doe"}]
    }
}

Possible responses are:

The response body is an array containing the labels of the objects that were chosen as best available.

["A-1", "A-2", "A-3"]

You can also ask seats.io to tell you whether the selected best available objects are next to each other (and on the same row):

{
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a',
    'bestAvailable': {number: 10, categories: ['balcony', 'stalls']},
    'indicateWhetherObjectsAreNextToEachOther': true
}

In that case, the response is not just a simple JavaScript array, but an object containing the best available seats and a boolean that indicates if the seats are next to each other:

{
 "objects": ["A-1", "A-2", "A-3"],
 "nextToEachOther": true   
}

Note that nextToEachOther is only set when selecting best available seats. When the algorithm picks booths or tables, nextToEachOther is not present in the response.

Note: here’s the same call in V2.

Using your own status

You can also use https://app.seats.io/api/changeStatus with a bestAvailable configuration as well. In that case you also have to povide the status in the request body, like so:

{
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a',
    'bestAvailable': {number: 10, categories: ['balcony', 'stalls']},
    'status': 'myCustomStatus'
}

Note

Note that for now, bestAvailable cannot be used when booking objects in multiple events at once (season tickets). General admission areas are also not supported.

Changing object status for multiple events at once (AKA season tickets)

Sometimes you need to change the status of objects for a whole bunch of events at once. A good example is when selling season tickets: the season ticket holder books a seat for all the events of the season.

Seats.io takes care of the all-or-nothing aspect of season tickets: either booking succeeds for all events, or it doesn’t succeed for any of them. So prefer doing a single change status call with a number of events as parameter, instead of changing the object status for each event individually.

Note: calling this API will be considered as “booking” for pricing purposes.

To change the status of objects in multiple events, POST a request to https://app.seats.io/api/changeStatus containing the following JSON body:

The request body should look like this:

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'eventKeys': ['smallTheatreEvent1', 'smallTheatreEvent2', 'smallTheatreEvent3'],
    'status': 'myCustomStatus',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

Responses are:

Curl

curl https://app.seats.io/api/changeStatus -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objects': ['A-3', 'A-5', 'A-7'], 'eventKeys': ['smallTheatreEvent1', 'smallTheatreEvent2', 'smallTheatreEvent3'], 'status': 'myCustomStatus', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note that temporarily reserving objects is also possible for season tickets.

Note: here’s the same call in V2.

Passing in extra data when changing status

Sometimes it’s necessary to pass in some custom data when changing the object status. For example, you might need to store the name of the person that booked a seat, to use in the tooltip of a rendered chart.

/changeStatus, /book and /release take an optional extraData object for each object ID in the request. extraData must be a JSON object with key value pairs (not a JSON primitive).

When an object gets released, and you don’t pass in extraData, the existing extraData is cleared.

POST to https://app.seats.io/api/changeStatus

{
    'objects': [
        { 'objectId': 'A-5', 'extraData': { 'name': 'John Doe' } },
        { 'objectId': 'A-6', 'extraData': { 'name': 'Jane Doe' } }
    ],
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'status': 'myCustomStatus',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

Possible responses are:

Curl:

curl https://app.seats.io/api/changeStatus -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objects': [{'objectId': 'A-5', 'extraData': {'name': 'John Doe'}}, {'objectId': 'A-6', 'extraData': {'name': 'Jane Doe'}}], 'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf', 'status': 'myCustomStatus', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Updating extra data

If you only want to change the extra data, but don’t want to change the status of an object, send a POST to https://app.seats.io/api/changeExtraData, with a request body like so:

{
    'objectId': 'E-6'
    'extraData': { 'name': 'John Doe' },
    'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

Response:

Curl

curl https://app.seats.io/api/changeExtraData -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'objectId': 'E-6', 'extraData': {'name': 'John Doe'}, 'eventKey': '767f0050-5af5-4cba-b262-7bf905dd5acf', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Orders

Passing in an order ID

When booking objects, you can optionally pass in an orderId. If you do so, you can retrieve all object IDs per orderId whenever you need (e.g. when printing tickets later on).
That way, you don’t even have to keep track of object IDs in your database.

If you send multiple book requests with the same orderId, all of the object IDs will be added to the order.
Releasing an object removes it from the order.

Retrieving the object IDs linked to an order

To retrieve the object IDs for a given orderId, send a GET request to https://app.seats.io/api/event/{eventKey}/orders/{orderId}/{secretKey}
The Response response will be an array of seat id’s, like this: ["A-3","A-5"].

Note: here’s the same call in V2.

Temporarily reserving objects

Reserving objects

Objects can be reserved for a certain time period. During this reservation period, other users cannot reserve the same seats.

By default the expiration time for reserved objects is 15 minutes, but this can be changed on the seats.io dashboard.

There are 2 ways to implement object reservation:

  1. through the reserveOnSelect renderer parameter. This parameter causes a rendered chart to reserve an object when a user clicks on it.
  2. or by invoking the /reserve API call from your server, which is documented below.

To reserve objects, you first need to generate a reservation token, which you then pass to the following API call:

POST to https://app.seats.io/api/reserve

{
    "objects": ["A-1", "A-2"],
    "event": "767f0050-5af5-4cba-b262-7bf905dd5acf",
    "publicKey": "d43266b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "reservationToken": "17378c14-ae6a-46a4-ada4-9c745a45e018"
}

When you’re ready to confirm a reservation (e.g. after payment was received), issue a /book or /changeStatus call, passing in the same reservation token that was used for the reservation. If no definitive booking is made before the reservation expires, the seat are released again.

Even for objects that are temporarily reserved, the reservationToken is an optional argument to /book and /changeStatus. You only need to pass it when it is the person that made the reservation who triggers the API call. If on the other hand you implemented some back office functionality in which venue managers can change the status of reserved objects, you don’t need to pass in the reservation token.

Reserving also works for season tickets. Just pass in an array of events instead of a single event.

Note: here’s the same call in V2.

Reserving best available objects

Temporarily reserving best available objects goes like this:

POST to https://app.seats.io/api/reserve

{
    "bestAvailable": {number: 10, categories: ["balcony", "stalls"]},
    "event": "767f0050-5af5-4cba-b262-7bf905dd5acf",
    "publicKey": "d43266b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "reservationToken": "17378c14-ae6a-46a4-ada4-9c745a45e018"
}

Note: here’s the same call in V2.

Generating a reservation token

All API calls that change the object status taken an optional reservationToken. This key has two purposes:

  1. assigning a unique token to a seat when temporarily reserving that seat (/api/reserve)
  2. verifying that the current user made a reservation, and thus is allowed to book or release a seat (/api/book, /api/release or /api/changeStatus)

By default, a reservation token is valid for 15 minutes. If you’re not happy with that setting, you can increase or decrease it on your dashboard.

To generate a reservationtoken, send a

POST to https://app.seats.io/api/reservationToken/{publicKey}

This call returns a JSON object:

{
  "reservationToken": "d972222f-11ee-4bfd-8411-af720d7f9f8a",
  "expiresAt": "2017-02-10T10:01:44.343Z",
  "expiresInSeconds": 900
}

Note: here’s the same call in V2.

Changing the expiration date of a reservation token

The expiration date of a reservation token can be changed. A good use case would be a reservation wizard, in which a user first has 15 minutes to select his seats, and then another 30 minutes to complete payment. In that case, it makes sense to change the token to expire in 30 minutes from now when the ticket buyer arrives at the payment page.

Note that the maximum validity of a reservation token is 2 hours. That means that a token that was created 10 minutes ago can at most be valid for another 1h50m.

To change the expiration date of reservation token, send a

PUT to https://app.seats.io/api/reservationToken/{secretKey}/ {reservationToken}/changeExpirationDate, with the duration in minutes for which the token is valid in the request body.

{
    "expiresInMinutes": 30
}

The response contains the new date at which the token will expire, and the number of seconds until expiration.

{
    "expiresAt": "2012-04-23T18:25:43.511Z",
    "expiresInSeconds": 900
}

Note: here’s the same call in V2.

Object Entrances

Larger venues and stadiums typically have more than one entrance. This entrance is of course information you’d like to print on the ticket, so that the attendee knows where to enter.

To do so, you can assign an entrance to sections and GA areas when designing the floor plan. Then, when you print the ticket, you can retrieve the entrance for a given object by sending a GET request to https://app.seats.io/api/chart/{secretKey}/{chartKey}/objectinfo/{label}.

The response will look like this:

{
    "section":{
        "entrance":"East"
    }
}

Note: in V2, the event reporting calls return the object entrances.

Reporting

Want to know which seats of an event are booked, and which ones are free? That’s where our reporting API calls come in handy.

To use them, send a GET request to a url that looks like this: https://app.seats.io/api/event/{secretKey}/{eventKey}/report/{reportType}.

Important note: All of the reporting API calls return a compressed (gzipped) response payload, even if you don’t send an Accept-Encoding: gzip header in your request.

The report types you can choose from are:

Here are examples of responses you’ll get for the different report types.

byStatus

{
    "free": [
        {
            "label": "C-11",
            "status": "free",
            "categoryLabel": "Ground Floor",
            "categoryKey": "4"
        },
        {
            "label": "GA",
            "status": "free",
            "categoryLabel": "Standing",
            "categoryKey": 6,
            "capacity": 100,
            "numBooked": 50
        }
    ],
    "booked": [
        {
            "label": "C-35",
            "status": "booked",
            "categoryLabel": "Balcony",
            "catgoryKey": "5",
            "extraData": {"name": "John Doe"}
        },
        {
            "label": "C-45",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "5"
        }
    ]
}

Note: here’s the same call in V2.

byCategoryLabel

{
    "Ground Floor": [
        {
            "label": "C-11",
            "status": "free",
            "categoryLabel": "Ground Floor",
            "categoryKey": "4"
        }
    ],
    "Balcony": [
        {
            "label": "C-35",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "5"
            "extraData": {"name": "John Doe"}
        },
        {
            "label": "C-45",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "5"
        }
    ],
    "Standing": [
        {
            "label": "GA",
            "status": "free",
            "categoryLabel": "Standing",
            "categoryKey": 6,
            "capacity": 100,
            "numBooked": 50
        }
    ]
}

Note: here’s the same call in V2.

byCategoryKey

{
    "4": [
        {
            "label": "C-11",
            "status": "free",
            "categoryLabel": "Ground Floor",
            "categoryKey": "4"
        }
    ],
    "5": [
        {
            "label": "C-35",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "5",
            "extraData": {"name": "John Doe"}
        },
        {
            "label": "C-45",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "5"
        }
    ],
    "6": [
        {
            "label": "GA",
            "status": "free",
            "categoryLabel": "Standing",
            "categoryKey": 6,
            "capacity": 100,
            "numBooked": 50
        }
    ]
}

Note: here’s the same call in V2.

byLabel

Multiple objects could have the same label, that’s why they’re returned as an array.

{
    "C-11": [
        {
            "label": "C-11",
            "status": "free",
            "categoryLabel": "Ground Floor",
            "categoryKey": "1"
        }
    ],
    "C-35": [
        {
            "label": "C-35",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "2",
            "extraData": {"name": "John Doe"}
    }
    ],
    "C-45": [
        {
            "label": "C-45",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "2"
        }
    ],
    "GA": [
        {
            "label": "GA",
            "status": "free",
            "categoryLabel": "Standing",
            "categoryKey": 6,
            "capacity": 100,
            "numBooked": 50
        }
    ]
}

Note: here’s the same call in V2.

bySection

{
    "Floor": [
        {
            "label": "C-11",
            "status": "free",
            "categoryLabel": "Ground Floor",
            "categoryKey": "1",
            "entrance": "Main entrance",
            "ticketType": "adult",
            "section": "Floor",
            "orderId": "order1"
        },
        {
            "label": "C-35",
            "status": "reservedByToken",
            "categoryLabel": "Balcony",
            "categoryKey": "5",
            "extraData": {"name": "John Doe"},
            "section": "Floor",
            "orderId": "order1",
            "holdToken": "5be320d5-10ca-4c8c-873c-40983c992ffc"
        }
    ],
    "Balcony": [
        {
            "label": "C-45",
            "status": "booked",
            "categoryLabel": "Balcony",
            "categoryKey": "2",
            "section": "Balcony",
            "orderId": "order2"
        }
    ],
    "NO_SECTION": [
        {
            "label": "GA",
            "status": "free",
            "categoryLabel": "Standing",
            "categoryKey": 6,
            "capacity": 100,
            "numBooked": 50
        }
    ]
}

Note: here’s the same call in V2.

Users

Creating Users

The API lets you create new user accounts. This is useful if you own a ticketing site, and you want your clients to draw their own charts without having to register manually at seats.io.

Send a POST to https://app.seats.io/api/createUser, with the following request body:

{
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

The response you’ll get back is

The response body contains the secret, public and designer keys of the new user. You should store those in your database to be able to use them afterwards.

{
    'secretKey': 'b16c8173-e61c-44b9-a35d-0d57c04a681e',
    'publicKey': 'f9b198c4-3805-4f0a-9f1c-e9f4111fd65a',
    'designerKey': 'de305d54-75b4-431b-adb2-eb6b9e546014'
}

From curl, you can do this:

curl https://app.seats.io/api/createUser -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the same call in V2.

Charts

List charts for a user

This API endpoint returns an array of chart keys, names and categories. It does not return the drawing details. For that, see Chart Details.

Send a GET request to https://app.seats.io/api/charts/{secretKey}

[
    {
        "key": "721181d8-cbb2-48f8-a369-7e4933622e94",
        "name": "A chart",
        "categories": [
            {
                "label": "Category A",
                "color": "#90CA77",
                "key": "1"
            },
            {
                "label": "Category B",
                "color": "#81C6DD",
                "key": "2"
            }
        ],
        "hasDraft": true
    },
    {
        "key": "821321d8-cae2-49f8-a369-7e4933622e94",
        "name": "Another chart",
        "categories": [
            {
            "label": "Category C",
            "color": "#90CA77",
            "key": "1"
            }
        ],
        "hasDraft": false
    }
]

Note: here’s the same call in V2.

Chart details

To fetch the full drawing (seats, categories, width, height, etc.), send a GET request to https://app.seats.io/api/chart/{chartKey}.json.
Note: this API call always returns a compressed (gzipped) response payload, even if you don’t send an Accept-Encoding: gzip header in your request.

The response will look something like this:

{
    "name": "Sample Chart",
    "categories": {
        "list": [
            {
                "label": "Balcony",
                "color": "#90CA77",
                "key": 1
            },
            {
                "label": "Ground Floor",
                "color": "#E9B64D",
                "key": 2
            },
            {
                "label": "Wheelchair",
                "color": "#336699",
                "key": 3
            }
        ]
    },
    "subChart": {
        "height": 678,
        "width": 947,
        "tables": [],
        "texts": [
            {
                "text": "ORGAN",
                "centerX": 480.57,
                "centerY": 666
            },
            {
                "text": "STAGE",
                "centerX": 476.9,
                "centerY": 55
            }
        ],
        "rows": [
            {
                "label": "A",
                "seats": [
                    {
                        "x": 363.9,
                        "y": 168,
                        "label": "12",
                        "categoryLabel": "Ground Floor"
                    },
                    {
                        "x": 383.9,
                        "y": 168,
                        "label": "10",
                        "categoryLabel": "Ground Floor"
                    }
                ]
            },
            {
                "label": "B",
                "seats": [
                    {
                        "x": 363.9,
                        "y": 188,
                        "label": "12",
                        "categoryLabel": "Ground Floor"
                    },
                    {
                        "x": 383.9,
                        "y": 188,
                        "label": "10",
                        "categoryLabel": "Ground Floor"
                    },
                    {
                        "x": 403.9,
                        "y": 188,
                        "label": "8",
                        "categoryLabel": "Ground Floor"
                    }
                ]
            }
        ]
    }
}

You can also get the draft version of a chart (provided the chart actually has a draft version of course):

https://app.seats.io/api/chart/{chartKey}.json/draft

Note: here’s the same call in V2.

Getting a chart draft version

To get the draft version of a chart, send a GET request to

https://app.seats.io/api/chart/{chartKey}.json/draft

If no draft exists for the chart, the response will be a 400 Bad Request.
Otherwise, the response will be a 200 OK with the same body as what the Chart details API endpoint returns.

Note: this API call always returns a compressed (gzipped) response payload, even if you don’t send an Accept-Encoding: gzip header in your request.

Note: here’s the same call in V2.

Creating a chart

To create a chart, send a POST request to https://app.seats.io/api/charts, with the following request body:

{
    "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "chart": {
         "name": "my chart",
         "venueType": "MIXED",
         "categories": [
            { "key": 1, "label": "Category 1", "color": "#aaaaaa"},
            { "key": 2, "label": "Category 2", "color": "#bbbbbb"}
        ]
     }
}

Curl:

curl https://app.seats.io/api/charts \
-X POST -H 'Content-Type: application/json' -d '{ "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a", chart: {"name": "my chart"}}'

The response is a JSON object with the key of the created chart.

{
    "key": "4250fffc-e41f-c7cb-986a-2c5e728b8c28"
}

Note: here’s the same call in V2.

Updating a chart

The name and categories of a chart can be updated by posting to https://app.seats.io/api/charts/{chartKey}.

To update the name of a chart, send the new name in the request body. If you don’t send a name, it will not change.

{
    "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "chart": {
        "name": "New name for my chart"
    }
}

To update categories, you must send an updated array of categories. This works as follows:

Suppose that this is the list of existing categories:

{
    "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "chart": {
        "categories": [
            { "key": 1, "label": "Category 1", "color": "#aaaaaa"},
            { "key": 2, "label": "Category 2", "color": "#bbbbbb"}
        ]
    }
}

and you send this update chart request:

{
    "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "chart": {
        "categories": [
            { "key": 2, "label": "My category 2"}
        ]
    }
}

then category 1 will be deleted, the label for category 2 will be set to “My category 2”, and the color of category 2 is left unchanged.

{
    "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a",
    "chart": {
        "categories": [
            { "key": 2, "label": "My category 2", "color": "#bbbbbb"}
        ]
    }
}

The response is a 204 - No Content.

Curl:

curl https://app.seats.io/api/charts/721181d8-cbb2-48f8-a369-7e4933622e94 \
-X POST -H 'Content-Type: application/json' -d '{ "secretKey": "c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a", chart: {"name": "my chart"}}'

Note: here’s the same call in V2.

Fetching the chart linked to an event

This API call returns the chart key, name and categories for the chart that’s linked to an event. It does not return the drawing details.

Send a GET request to https://app.seats.io/api/chart/{secretKey}/event/{eventKey}, the response will look like this:

    {
        "key": "721181d8-cbb2-48f8-a369-7e4933622e94",
        "name": "A chart",
        "categories": [
            {
                "label": "Category A",
                "color": "#90CA77",
                "key": "1"
            },
            {
                "label": "Category B",
                "color": "#81C6DD",
                "key": "2"
            }
        ],
        "hasDraft": false
    }

Note: there’s no direct replacement for this call in V2. You first have to retrieve the event, and then use the chartKey to retrieve the published chart version

Copy a chart

To create a copy of a chart, send a POST to https://app.seats.io/api/chart/copy, with the following request body:

{
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a',
    'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace',
    'chartName': 'Copy of this venue'
}

Note that events linked to the original chart won’t be copied.

The response will be the chartKey of the new chart. You can store this in your database, and use it to refer to the newly created chart in the future.

Curl:

curl https://app.seats.io/api/chart/copy -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

To copy the draft version of a chart into a new chart, send a POST to https://app.seats.io/api/chart/copy/draft. If the chart does not have a draft version, this call returns a 400 (bad request).

Note: here’s the same call in V2.

Archive a chart

Charts cannot be hard deleted. However, if you don’t need them anymore, you can archive them. Archived charts are not displayed on the chart overview of the dashboard, but they’re visible in the archive.

To archive a chart via the REST API, send a POST to https://app.seats.io/api/chart/{secretKey}/{chartKey}/archive, with these parameters:

The response will be HTTP 200 (ok) if the chart was found and not yet archived, or HTTP 400 (bad request) otherwise.

Curl

curl https://app.seats.io/api/chart/c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a/667f0050-5af5-4cba-b262-7bf905dd5ace/archive -v -X POST

Note: here’s the same call in V2.

Unarchive a chart

Send a POST to https://app.seats.io/api/chart/{secretKey}/{chartKey}/unarchive.

The response will be HTTP 200 (ok) if the chart was found and could be unarchived, or HTTP 400 (bad request) otherwise.

Curl

curl https://app.seats.io/api/chart/c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a/667f0050-5af5-4cba-b262-7bf905dd5ace/unarchive -v -X POST</code>

Note: here’s the same call in V2.

Thumbnails

Chart thumbnails are static SVG representations of a seating chart. This means that you cannot interact with the objects on the chart. You typically use them when showing a list of charts to a user, e.g. when integrating seats.io into your backoffice system.

Keep in mind that you should not expect thumbnails to contain all details of the chart. E.g. the number of seats in a thumbnail might be slightly different than the actual number of seats. This is done to keep the size of the thumbnails small. To get a high-detail static representation of a single chart, use print mode.

To show a thumbnail, link to https://app.seats.io/api/chart/{chartKey}/thumbnail.

E.g. <img src="https://app.seats.io/api/chart/demoChartSmallTheatre/thumbnail" />

will look like this:

The thumbnail for a draft version can be fetched at https://app.seats.io/api/chart/{chartKey}/thumbnail/draft.

Note: here’s the same call in V2.

Publishing a draft version

Charts in seats.io can have 2 versions: a published version and a draft version. All charts start with a published version only. Changes that you make to that version are not immediately visible on rendered charts. Instead, a draft version is created when you modify the chart. You have to publish this draft version to make the changes visible to ticket buyers.

To publish a draft version, send a POST to https://app.seats.io/api/chart/{secretKey}/{chartKey}/publishDraft.

A 400 (bad request) is returned when the chart does not exist, or when the chart does not have a draft version.

Note: here’s the same call in V2.

Discarding a draft version

The draft version of a chart can be removed. To do so, send a POST to https://app.seats.io/api/chart/{secretKey}/{chartKey}/discardDraft.

A 400 (bad request) is returned when the chart does not exist, or when the chart does not have a draft version.

Note: here’s the same call in V2.

Events

Charts must be linked to events before you can show them to tickets buyers. You have to provide an event key; that’s the ID the event in your own database. It could be for example the primary key of the event record.

There is no separate API call to create an event. The first time linkChartToEvent is called, the event is created in seats.io. Subsequent calls just modify the existing event.

Event details

Send a GET to https://app.seats.io/api/event/{secretKey}/{eventKey}/details.

The response will be:

{
    "chartKey": "667f0050-5af5-4cba-b262-7bf905dd5ace",
    "bookWholeTables": true,
    "bestAvailable": true // true when focal point has been set on the chart linked to the event
}

Note: here’s the same call in V2.

Object status

Send a GET to https://app.seats.io/api/event/{secretKey}/{eventKey}/object/{label}.

The response for a regular, non-GA object will be:

{
    "status": "booked",
    "ticketType": "adult",
    "extraData": {
        "foo": "bar"
    }
}

And for a GA area:

{
    "status": "free",
    "quantity": 10
}

GA areas remain in status ‘free’ as long as they are not fully booked. ‘quantity’ is the number of booked tickets.

Note: here’s the same call in V2.

Create/Update a single event

Send a POST to https://app.seats.io/api/linkChartToEvent, with this request body:

{
    'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace',
    'eventKey': '2345',
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

In curl, this looks like this:

curl https://app.seats.io/api/linkChartToEvent -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace', 'eventKey': '2345', 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: here’s the call in V2 to create an event and to update an event.

Create/Update multiple events

Send a POST to https://app.seats.io/api/linkChartToEvents, with the following request body:

{
    'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace',
    'eventKeys': ['2345','2346','2347'],
    'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'
}

Curl

curl https://app.seats.io/api/linkChartToEvents -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d "{'chartKey': '667f0050-5af5-4cba-b262-7bf905dd5ace', 'eventKeys': ['2345','2346','2347'], 'secretKey': 'c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a'}"

Note: there’s no call in V2 that allows creating or updating multiple events at once. Instead, you have to invoke the calls to create or update a single event multiple times.

Changing book whole tables

Events with charts containing tables can be configured to either allow bookings for whole tables, or for individual seats.

To change this setting, send a POST to https://app.seats.io/api/event/{secretKey}/{eventKey}/bookWholeTables/<value>.

The response will be HTTP 200 (OK) if the event was found and the “book whole tables” setting was successfully changed, and HTTP 400 (Bad Request) otherwise.

Curl

curl https://app.seats.io/api/event/c7366b35-b08d-4fc3-b8ab-f3e706dd3a2a/667f0050-5af5-4cba-b262-7bf905dd5ace/bookWholeTables/true -v -X POST

Note: here’s the same call in V2.

Listing status changes

You can get a list of all status changes for an event with this GET call:

https://app.seats.io/api/event/{secretKey}/{eventKey}/statusChanges

The response is a JSON array, containing all status changed ordered by oldest to newest.

[
    {
        'eventId':101,
        'objectLabelOrUuid':'A-1',
        'quantity':1,
        'status':'booked',
        'date':'2014-05-16T16:04:11.657+02:00',
        'id':1597
    },
    {
        'eventId':101,
        'objectLabelOrUuid':'A-2',
        'quantity':1,
        'status':'booked',
        'date':'2014-05-16T16:04:11.658+02:00',
        'id':1598
    }
    ...
]

Note: here’s the same call in V2.