API v2

This is the documentation for version 2 of the seats.io API.

General

Authentication

When calling the seats.io the seats.io API, you need to authenticate yourself. To do so, you need to include your secret key in each request. You can manage your API keys on the settings page.
Your secret key carries many privileges, so it’s very important to keep it to yourself:

Authentication to the API is performed via HTTP Basic Auth. Provide your secret key as the username value. You do not need to provide a password.
API requests without authentication will fail.

Example request

curl https://api.seatsio.net/charts -u aSecretKey:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).

In general, you need to set a header called Authorization with value “Basic x”, where x is your secret key with a colon, base64 encoded (“aSecretKey:” encoded in base64 is “YVNlY3JldEtleTo=”).

Like so:

curl https://api.seatsio.net/charts -H "Authorization: Basic YVNlY3JldEtleTo="

HTTPS

All requests must be made over HTTPS. If you try to access the seats.io API over HTTP, you’ll receive a 301 “Moved Permanently”. The location header in the response points to the requested URL, but over HTTPS.

The base URL for all API calls is https://api.seatsio.net

gzip

Response payloads are not compressed by default.
However, you can request a gzipped response by sending a Accept-Encoding: gzip header with your request.

Errors

Seats.io uses standard HTTP error codes to indicate problems. Some examples:

Have a look at the response body to see what went wrong exactly (except in case of 401 or 403 errors, in that case the response body is empty). The response body of a failed request looks like this:

{
    "status": 400,
    "messages": ["url is a required query parameter", "some other error message"],
    "requestId": "27378c14-ae6a-46a4-ada4-9c745a45e018"
}

In most cases, messages is an array that contains exactly one error message. But there might be more than one, e.g. when a request results in multiple validation errors.

The request ID is useful for us to debug any errors you encounter. Please mention it when contacting us.

Pagination

All resources that have support for bulk fetches (i.e. GETting a list of resources) have a common structure: they return a paginated result, and they take at least two query parameters: start_after_id and limit.
Seats.io uses cursor-based pagination: the start_after_id takes an existing object ID value.

Arguments

Response format

Expanding objects

Some objects contain references to other objects. For example, a chart can have a list of associated events. Those objects can be expanded inline, using the expand request parameter. Objects that can be expanded are noted in this documentation.
This query parameter applies to the response of that request only.

URI encoding

Don’t forget to URI-encode string parameters in URLs.

For example, the reporting call /reports/events/{eventKey}/byCategoryLabel/{label} takes a label parameter. When this parameter contains reserved ASCII characters such as ‘/’ and ‘:’, or non ASCII characters such as ‘ã’, you must apply percent-encoding. E.g. Balcão Nobre becomes Balc%C3%A3o%20Nobre.

Note that our client libraries do this under the hood. You don’t have to encode anything when using them.

Client libraries

Interacting with the API becomes even easier if you use one of our client libraries:

If you need a client library in another language, please let us know.

Core resources

Objects

Object statuses introduction

Out of the box, seats.io offers three statuses for objects (e.g. seats) within an event: free, reservedByTokenand booked.

Initially, all objects start in status free.

Suppose then that you’ve enabled holdOnSelect when rendering a chart. In that case, as soon as the ticket buyer clicks on a seat, it goes to status reservedByToken. Note that this is a legacy status name: in the past, holding an object was known as reserving an object. We kept the status reservedByToken to not break existing integrations.

reservedByToken means that the object is temporarily ‘locked’ so that only the person that originally held it can confirm the booking through a secret hold token. If no booking arrives within 15 minutes (by default) of holding the objects, seats.io automatically releases the held objects again.

The exact meaning of a booked seat depends on your sales process, but this would typically be after the payment has been processed. An object can go from free to booked directly, or from free to reservedByToken to booked. That’s up to you.

There are API calls to /book and /release seats, and also tohold them if you prefer to do that yourself instead of relying on the chart renderer parameter holdOnSelect. You can also assign other, custom statuses. Say you want to create a separate status ‘VIP’, which indicates that a seat can only be booked by people that are logged in on your site as VIP. That’s where /changeStatus comes into place.

Book objects

Changes the object status to ‘booked’. Booked seats are not selectable on a rendered chart.

POST /events/{eventKey}/actions/book

POST /events/{eventKey}/actions/book?expand=labels
// PHP
$seatsioClient->events->book("event1", ["A-3", "A-5", "A-7"]);
// C#
Client.Events.Book("event1", new [] { "A-3", "A-5", "A-7" });
// Java
client.events.book("event1", Arrays.asList("A-3", "A-5", "A-7"));
# Python
client.events.book("event1", ["A-3", "A-5", "A-7"])

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 a “booking” for pricing purposes.

Request

{
    'objects': ['A-3', 'A-5', 'A-7']
}

Response

Without expand=labels
204 - No Content

With expand=labels
200 - ok

{
    "labels": {
        "A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },  
        "A-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        }
    }
}

Release objects

Changes the object status to ‘free’. Free seats are selectable on a rendered chart.

Note: releasing objects can also be used to cancel objects that are temporarily held.

POST /events/{eventKey}/actions/release

POST /events/{eventKey}/actions/release?expand=labels
// PHP
$seatsioClient->events->release("event1", ["A-3", "A-5", "A-7"]);
// C#
Client.Events.Release("event1", new [] { "A-3", "A-5", "A-7" });
// Java
client.events.release("event1", Arrays.asList("A-3", "A-5", "A-7"));
# Python
client.events.release("event1", ["A-3", "A-5", "A-7"])

Request

{
    'objects': ['A-3', 'A-5', 'A-7']
}

Response

Without expand=labels
204 - No Content

With expand=labels
200 - ok

{
    "labels": {
        "A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },  
        "A-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        }
    }
}

Temporarily hold objects

Objects can be held for a certain time period. During this period, other users cannot hold or book the same seats.

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

There are 2 ways to implement temporarily holding objects:

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

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

POST /events/{eventKey}/actions/hold

POST /events/{eventKey}/actions/hold?expand=labels
{
    "objects": ["A-1", "A-2"],
    "holdToken": "17378c14-ae6a-46a4-ada4-9c745a45e018"
}
// PHP
$seatsioClient->events->hold("event1", ["A-1", "A-2"], "17378c14-ae6a-46a4-ada4-9c745a45e018");
// C#
Client.Events.Hold("event1", new [] { "A-1", "A-2" }, "17378c14-ae6a-46a4-ada4-9c745a45e018");
// Java
client.events.hold("event1", Arrays.asList("A-1", "A-2"), "17378c14-ae6a-46a4-ada4-9c745a45e018");
# Python
client.events.hold("event1", ["A-1", "A-2"], hold_token="17378c14-ae6a-46a4-ada4-9c745a45e018")

After invoking this API call, the objects get the status reservedByToken. This is a legacy status name: in the past, holding an object was known as reserving an object. We kept the status reservedByToken to not break existing integrations.

When you’re ready to confirm the booking for a held object (e.g. after payment was received), issue a /book or /change-object-status call, passing in the same hold token that was used for acquiring the hold.

If no definitive booking is made before the hold expires, the seat are released again. And if you want to cancel a hold before the hold period expires, you just release the objects.

Even for objects that are held, the hold token is an optional argument to /book and /change-object-status. You only need to pass it when it is the person that made the hold 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 held objects, you don’t need to pass in the hold token.

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

Response

Without expand=labels
204 - No Content

With expand=labels
200 - ok

{
    "labels": {
        "A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },  
        "A-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        }
    }
}

Change object status

Changes the object status to a custom status of your choice.

POST /events/{eventKey}/actions/change-object-status

POST /events/{eventKey}/actions/change-object-status?expand=labels
// PHP
$seatsioClient->events->changeObjectStatus("event1", ["A-3", "A-5", "A-7"], "myCustomStatus");
// C#
Client.Events.ChangeObjectStatus("event1", new [] { "A-3", "A-5", "A-7" }, "myCustomStatus");
// Java
client.events.changeObjectStatus("event1", Arrays.asList("A-3", "A-5", "A-7"), "myCustomStatus");
# Python
client.events.change_object_status("event1", ["A-3", "A-5", "A-7"], status="myCustomStatus")

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 a “booking” for pricing purposes.

Request

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'status': 'myCustomStatus'
}

Response

Without expand=labels
204 - No Content

With expand=labels
200 - ok

// seats in rows:
{
    "labels": {
        "A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },  
        "A-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        }
    }
}

// seats on tables:
{
    "labels": {
        "T1-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "T1", "type": "table" },
        },  
        "T1-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "T1", "type": "table" },
        }
    }
}

// seats in sections:
{
    "labels": {
        "STA-A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
            "section": { "label": "Stalls" },
            "entrance": { "label": "Red" }
        },  
        "STA-A-5": { 
            "own": { "label": "5", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
            "section": { "label": "Stalls" },
            "entrance": { "label": "Red" }
        }
    }
}

// booths:
{
    "labels": {
        "booth1": { 
            "own": { "label": "booth1", "type": "booth" }
        }
    }
}

// bookable tables:
{
    "labels": {
        "T1": { 
            "own": { "label": "T1", "type": "table" }
        }
    }
}

// general admission areas:
{
    "labels": {
        "GA1": { 
            "own": { "label": "Standing", "type": "generalAdmission" }
        }
    }
}

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 a “booking” for pricing purposes.

POST /events/{eventKey}/actions/change-object-status
POST /events/{eventKey}/actions/book
POST /events/{eventKey}/actions/hold
POST /events/{eventKey}/actions/release
// PHP
$seatsioClient->events->changeObjectStatus("event1", [["objectId" => "GeneralAdmission1", "quantity" => 3]], "myCustomStatus");
// C#
Client.Events.ChangeObjectStatus("event1", new [] { new ObjectProperties("GeneralAdmission1", 3")  }, "myCustomStatus");
// Java
client.events.changeObjectStatus("event1", Arrays.asList(new ObjectProperties("GeneralAdmission1", 3)), "myCustomStatus");
# Python
client.events.change_object_status("event1", [ObjectProperties("GeneralAdmission1", quantity=3)], status="myCustomStatus")

Request

{
    'objects': [{'objectId': 'GeneralAdmission1', 'quantity': 3}],
    'status': 'myCustomStatus'
}

Best available

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.

Maximum load

A lot of things happen in the background when booking best available seats. We

  1. retrieve the already booked seats from the database
  2. determine the best available ones that are free
  3. book those seats

This requires quite a bit of processing, but on the CPU and on the database side. That’s why our API currently supports about 1.250 best available booked seats per minute (per event). Beyond that number, responses will start coming in slower, and eventually time our after 30 seconds.

If you expect a higher load, please let us know.

How to use it

POST /events/{eventKey}/actions/change-object-status
POST /events/{eventKey}/actions/book
POST /events/{eventKey}/actions/hold
// PHP
$seatsioClient->events->changeBestAvailableObjectStatus("event1", 10, "myCustomStatus", ["balcony", "stalls"]);
// C#
Client.Events.ChangeBestAvailableObjectStatus("event1", new BestAvailable(10, new [] { "balcony", "stalls" }, "myCustomStatus");
// Java
client.events.changeObjectStatus("event1", new BestAvailable(10, Arrays.asList("balcony", "stalls")), "myCustomStatus");
# Python
client.events.change_best_available_object_status("event1", 
    number=10, 
    categories=["balcony", "stalls"], 
    status="myCustomStatus")

Request

{
    "bestAvailable": {
        number: 2,
        categories: ["balcony", "stalls"],
        extraData: [{"name": "John Doe"}, {"name": "Jane Doe"}]
    }
}

Response

200 - ok

{
    "objects": ["A-1", "A-2", "A-3"],
    "nextToEachOther": true,
    "labels": {
        "A-1": { 
            "own": { "label": "1", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },  
        "A-2": { 
            "own": { "label": "2", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        },
        "A-3": { 
            "own": { "label": "3", "type": "seat" },
            "parent": { "label": "A", "type": "row" },
        }
    }
}

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.

Multiple events (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 a “booking” for pricing purposes.

POST /seasons/actions/change-object-status
POST /seasons/actions/book
POST /seasons/actions/release
POST /seasons/actions/hold
// PHP
$seatsioClient->events->changeObjectStatus(["event1", "event2", "event3"], ["A-3", "A-5", "A-7"], "myCustomStatus");
// C#
Client.Events.ChangeObjectStatus(new [] { "event1", "event2", "event3" }, new [] { "A-3", "A-5", "A-7"  }, "myCustomStatus");
// Java
client.events.changeObjectStatus(Arrays.asList("event1", "event2", "event3"), Arrays.asList("A-3", "A-5", "A-7"), "myCustomStatus");
# Python
client.events.change_object_status(
    ["event1", "event2", "event3"], 
    ["A-3", "A-5", "A-7"],
    status="myCustomStatus")

Request

{
    'objects': ['A-3', 'A-5', 'A-7'],
    'events': ['event1', 'event2', 'event3'],
    'status': 'myCustomStatus'
}

Response

204 - No Content

Extra data

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.

/change-object-status, /book, /release and /hold 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.

{
    'objects': [
        { 'objectId': 'A-5', 'extraData': { 'name': 'John Doe' }},
        { 'objectId': 'A-6', 'extraData': { 'name': 'Jane Doe' }}
    ]
}
// PHP
$objects = [
  ["objectId" => "A-5", "extraData" => ["name" => "John Doe"]],
  ["objectId" => "A-6", "extraData" => ["name" => "Jane Doe"]]
];
$seatsioClient->events->book("event1", $objects);
// C#
var objects = new [] {
    new ObjectProperties("A-5", new Dictionary<string, object> {{"name", "John Doe"}}),
    new ObjectProperties("A-6", new Dictionary<string, object> {{"name", "Jane Doe"}})
};
Client.Events.Book("event1", objects);
// Java
List<ObjectProperties> objects = Arrays.asList(
    new ObjectProperties("A-5", ImmutableMap.of("name", "John Doe")),
    new ObjectProperties("A-6", ImmutableMap.of("name", "Jane Doe"))
);
client.events.book("event1", objects);
# Python
objects= [
    ObjectProperties("A-5", extra_data={"name": "John Doe"}),
    ObjectProperties("A-6", extra_data={"name": "Jane Doe"})
]
client.events.book("event1", objects)

For sale / not for sale

Sometimes you don’t want ticket buyers to be able to choose from all seats in a venue. For example:

In those cases, you can use our ‘for sale’ and ‘not for sale’ API calls to mark sections, rows, seats or categories as for sale or not for sale, without having to change the status of those individual seats. Doing so is much more convenient (and faster) than sending status changes in batch.

You can embed the event manager to allow your admin users to modify the for sale configuration.

Note that ’for sale and ‘not for sale’ do not replace seat bookings. Each time you assign a seat to someone, you must also use our status change API, otherwise the availability management will not work properly. One of the reasons is that changes made by ‘for sale’ and ‘not for sale’ don’t support live updates, so they are not pushed to all ticket buyers. As a result, ticket buyers may not see the correct availability information unless there is also the correct status change API call.

In effect, it is a condition of use of seats.io that there is a strict mirroring between assigning a seat and a /change-object-status or /book API call. Breach of this rule may lead to immediate suspension of the account without warning.

There’s a rate limit of 5 calls per event per day on the for sale/not for sale API calls.

Mark objects as not for sale

This API call marks the passed in objects and categories as not for sale, while marking all other objects as for sale.

POST /events/{eventKey}/actions/mark-as-not-for-sale
// PHP
$seatsioClient->events->markAsNotForSale("event34", ["section1", "section2"], ["category1", "category2"]);
// C#
Client.Events.MarkAsNotForSale("event34", new [] { "section1", "section2" }, new [] { "category1", "category2" });
// Java
client.events.markAsNotForSale("event34", Arrays.asList("section1", "section2"), Arrays.asList("category1", "category2"));
# Python
client.events.mark_as_not_for_sale("event34", objects=["section1", "section2"], categories=["category1", "category2"])

Request

{
    "objects": ["section1", "section2"],
    "categories": ["category1", "category2"]
}

Only objects that satisfy ‘objects’ or ‘categories’ will become unselectable. All other objects are selectable, unless their status is not equal to ‘free’.

Examples

To mark all objects that are either inside ‘section1’ or that have ‘category1’ as not for sale:

{
    "objects": ["section1"],
    "categories": ["category1"]
}

To mark seat A-1 and A-2 as not for sale:

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

To mark all seats in row A as not for sale:

{
    "objects": ["A"]
}

Example request

curl https://api.seatsio.net/events/event34/actions/mark-as-not-for-sale \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"objects": {"section1"}}'

Response

204 - No Content

There’s a rate limit of 5 calls per day per event. If that rate limit if reached, a 429 (Too Many Requests) is returned. The Retry-After header indicates how many seconds you have to wait before trying again.

Mark objects as for sale

This API call marks the passed in objects and categories as for sale, while marking all other objects as not for sale.

POST /events/{eventKey}/actions/mark-as-for-sale
// PHP
$seatsioClient->events->markAsForSale("event34", ["section1", "section2"], ["category1", "category2"]);
// C#
Client.Events.MarkAsForSale("event34", new [] { "section1", "section2" }, new [] { "category1", "category2" });
// Java
client.events.markAsForSale("event34", Arrays.asList("section1", "section2"), Arrays.asList("category1", "category2"));
# Python
client.events.mark_as_for_sale("event34", objects=["section1", "section2"], categories=["category1", "category2"])

Request

{
    "objects": ["section1", "section2"],
    "categories": ["category1", "category2"]
}

Only objects that satisfy ‘objects’ or ‘categories’ will become selectable (and bookable). All other objects are not selectable, and trying to book them results in a bad request.

Note that even though object is marked for sale, it’s still not selectable if its status is not free.

Examples

To mark all objects for sale that are either inside ‘section1’ or that have ‘category1’:

{
    "objects": ["section1"],
    "categories": ["category1"]
}

To mark seat A-1 and A-2 for sale:

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

To mark all seats in row A for sale:

{
    "objects": ["A"]
}

Example request

curl https://api.seatsio.net/events/event34/actions/mark-as-for-sale \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"objects": {"section1"}}'

Response

204 - No Content

There’s a rate limit of 5 calls per day per event. If that rate limit if reached, a 429 (Too Many Requests) is returned. The Retry-After header indicates how many seconds you have to wait before trying again.

Mark all objects as for sale

This API call marks all objects as for sale, which means resetting the list of objects and categories that were previously passed in by mark-as-for-sale or mark-as-not-for-sale.

POST /events/{eventKey}/actions/mark-everything-as-for-sale
// PHP
$seatsioClient->events->markEverythingAsForSale("event34");
// C#
Client.Events.MarkEverythingAsForSale("event34");
// Java
client.events.markEverythingAsForSale("event34");
# Python
client.events.mark_everything_as_for_sale("event34")

Example request

curl https://api.seatsio.net/events/event34/actions/mark-everything-as-for-sale \
-u aSecretKey: -X POST

Response

204 - No Content

Charts

List all charts

Returns a paginated list of charts you’ve previously created. The charts are returned in reverse chronological order: the most recently created charts will appear first in the list.

GET /charts

GET /charts?filter=london
GET /charts?tag=WestEnd
GET /charts?expand=events
// PHP
$seatsioClient->charts->listFirstPage(); // last 20 charts that were created. 20 is the default page size when fetching charts.
$seatsioClient->charts->listFirstPage(null, 10); // last 10 charts that were created
$seatsioClient->charts->listAll(); // iterator that loops over all charts, which does a REST call to fetch the next page when required
// C#
Client.Charts.ListFirstPage();  // last 20 charts that were created. 20 is the default page size when fetching charts.
Client.Charts.ListFirstPage(pageSize: 10);  // last 10 charts that were created
Client.charts.ListAll(); // iterator that loops over all charts, which does a REST call to fetch the next page when required
// Java
client.charts.listFirstPage(); // last 20 charts that were created. 20 is the default page size when fetching charts.
client.charts.listFirstPage(null, 10); // last 10 charts that were created
client.charts.listAll(); // IEnumerable<Chart>, which does a REST call to fetch the next page when required
# Python
client.charts.list_first_page() # last 20 charts that were created. 20 is the default page size when fetching charts.
client.charts.list_first_page(page_size = 10) # last 10 charts that were created
client.charts.list() # iterable, which does a REST call to fetch the next page when required

Example

Example request

curl https://api.seatsio.net/charts -u aSecretKey:

Example response

 {
    "next_page_starts_after": 12,
    "items":[
        {
            "name":"chart1",
            "id":"20",
            "key":"6451436c-24fb-11e7-93ae-92361f002671",
            "status":"PUBLISHED",
            "tags": [],
            "archived": false,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
        },
        {
            "name":"chart2",
            "id":"19",
            "key":"749b9650-24fb-11e7-93ae-92361f002671",
            "status":"PUBLISHED_WITH_DRAFT",
            "tags": ["tag1", "tag2"],
            "archived": false,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail",
            "draftVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../draft/.../thumbnail"
        }
    ]
}

The status of a chart can be either
- “NOT_USED”: there are no events linked to the chart
- “PUBLISHED”: there’s an event linked to the chart, and there’s no draft version
- “PUBLISHED_WITH_DRAFT”: there’s an event linked to the chart, and a draft version exists

publishedVersionThumbnailUrl (and draftVersionThumbnailUrl if applicable) are URLs that return an SVG thumbnail for the chart. Those thumbnails are served from our CDN, so they load fast.

Query parameters

This is a paginated API endpoint, so the normal pagination query params (limit, start_after_id and end_before_id) are applicable. See pagination for more info.

// PHP
$seatsioClient->charts->listFirstPage((new ChartListParams())->withFilter('london')); // newest charts having 'london' in their name
$seatsioClient->charts->listFirstPage((new ChartListParams())->withTag('WestEnd')); // newest charts tagged 'WestEnd'
$seatsioClient->charts->listFirstPage((new ChartListParams())->withExpandEvents(true)); // newest charts and a list of linked events
// C#
Client.Charts.ListFirstPage(filter: "london")); // newest charts having 'london' in their name
Client.Charts.ListFirstPage(tag: "foo"); // newest charts tagged 'WestEnd'
Client.Charts.ListFirstPage(expandEvents: true); // newest charts and a list of linked events
// Java
client.charts.listFirstPage(new ChartListParams().withFilter("london")); // newest charts having 'london' in their name
client.charts.listFirstPage(new ChartListParams().withTag("WestEnd")); // newest charts tagged 'WestEnd'
client.charts.listFirstPage(new ChartListParams().withExpandEvents(true)); // newest charts and a list of linked events
# Python
client.charts.list_first_page(filter="london") # newest charts having 'london' in their name
client.charts.list_first_page(tag="foo") # newest charts tagged 'WestEnd'
client.charts.list_first_page(expandEvents=True) # newest charts and a list of linked events

Example response:

{
    "items":[
        {
            "name":"chart1",
            "id":"20",
            "key":"6451436c-24fb-11e7-93ae-92361f002671",
            "status":"PUBLISHED",
            "archived": false,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail",
            "events": [
                {
                    "id": "50",
                    "bookWholeTables": false,
                    "key": "eventKey2"
                },
                {
                    "id": "49",
                    "bookWholeTables": false,
                    "key": "event34"
                }
            ]
        },
        {
            "name":"chart2",
            "id":"19",
            "key":"749b9650-24fb-11e7-93ae-92361f002671",
            "status":"NOT_USED",
            "archived": false,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
        }
    ]
}

Retrieve a chart

This endpoint retrieves the metadata that is shared between the published and draft versions of a chart (id, key, status, archived etc).

To fetch the actual contents of the chart (including categories), use the endpoint to retrieve a chart verison

GET /charts/{key}

GET /charts/{key}?expand=events
// PHP
$seatsioClient->charts->retrieve("749b9650-24fb-11e7-93ae-92361f002671");

$seatsioClient->charts->retrieveWithEvents("749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Charts.Retrieve("749b9650-24fb-11e7-93ae-92361f002671"));

Client.Charts.Retrieve("749b9650-24fb-11e7-93ae-92361f002671", expandEvents: true));
// Java
client.charts.retrieve("749b9650-24fb-11e7-93ae-92361f002671");

client.charts.retrieveWithEvents("749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.charts.retrieve("749b9650-24fb-11e7-93ae-92361f002671")

client.charts.retrieve_with_events("749b9650-24fb-11e7-93ae-92361f002671")

Query parameters

Example request

curl https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671 \
-u aSecretKey:

Example response

A JSON object that represents the chart:

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

And with expand=events:

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail",
    "events": [
        {
            "id": "50",
            "bookWholeTables": false,
            "key": "eventKey2"
        },
        {
            "id": "49",
            "bookWholeTables": false,
            "key": "event34"
        }
    ]
}

Error 404 (Not Found) is returned when the chart does not exist.

Retrieve a chart version

Each chart has a published version and an optional draft version. Those versions contain the acutal contents of the chart: categories, rows, seats etc. The endpoints below allow you to fetch exactly that data.

To retrieve properties that are shared between the draft and published version, call the endpoint to retrieve a chart.

Retrieve the published version of a chart

GET /charts/{chartKey}/version/published
// PHP
$drawing = $seatsioClient->charts->retrievePublishedVersion("749b9650-24fb-11e7-93ae-92361f002671");
echo $drawing["venueType"];
// C#
var drawing = Client.Charts.RetrievePublishedVersion("749b9650-24fb-11e7-93ae-92361f002671"));
Console.WriteLine(chart.VenueType);
// Java
Map<?, ?> drawing = client.charts.retrievePublishedVersion("749b9650-24fb-11e7-93ae-92361f002671");
System.out.println(drawing.get("venueType"));
# Python
drawing = client.charts.retrieve_published_version("749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl https://api.seatsio.net/charts/aChartKey/version/published \
-u aSecretKey:

Example response

A JSON object that represents the published version of the chart:

{
    "name": "A demo chart",
    "categories": { ... },
    "subChart": {
        "rows": [ ... ]
    }
    ...
}

Retrieve the draft version of a chart

GET /charts/{chartKey}/version/draft
// PHP
$drawing = $seatsioClient->charts->retrieveDraftVersion("749b9650-24fb-11e7-93ae-92361f002671");
echo $drawing["venueType"];
// C#
var drawing = Client.Charts.RetrieveDraftVersion("749b9650-24fb-11e7-93ae-92361f002671"));
Console.WriteLine(chart.VenueType);
// Java
Map<?, ?> drawing = client.charts.retrieveDraftVersion("749b9650-24fb-11e7-93ae-92361f002671");
System.out.println(drawing.get("venueType"));
# Python
drawing = client.charts.retrieve_draft_version("749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl https://api.seatsio.net/charts/aChartKey/version/draft \
-u aSecretKey:

Example response

A JSON object that represents the draft version of the chart:

{
    "name": "A draft chart",
    "categories": { ... },
    "subChart": {
        "rows": [ ... ]
    }
    ...
}

Error 404 (Not Found) is returned when the chart does not have a draft version.

Create a chart

Charts can be created by posting a JSON object that represents the chart to /charts. This request body is optional: an empty untitled chart is created when an empty request body is sent.

POST /charts
// PHP
$cat1 = ['key' => 1, 'label' => 'Category 1', 'color' => '#aaaaaa'];
$cat2 = ['key' => 2, 'label' => 'Category 2', 'color' => '#bbbbbb'];
$seatsioClient->charts->create("my chart", "MIXED", [$cat1, $cat2]);
// C#
var category1 = new Category(1, "Category 1", "#aaaaaa");
var category2 = new Category(2, "Category 2", "#bbbbbb");
var drawing = Client.Charts.Create("my chart", "MIXED", new [] { category1, category2 });
// Java
Category category1 = new Category(1, "Category 1", "#aaaaaa");
Category category2 = new Category(2, "Category 2", "#bbbbbb");
client.charts.create("my chart", "MIXED", Arrays.asList(category1, category2));
# Python
client.charts.create(
    categories=[
        {"key": 1, "label": "Category 1", "color": "#aaaaaa"},
        {"key": 2, "label": "Category 2", "color": "#bbbbbb"}
    ])

Request

{
    "name": "my chart",
    "venueType": "TABLES",
    "categories": [
        { "key": 1, "label": "Category 1", "color": "#aaaaaa"},
        { "key": 2, "label": "Category 2", "color": "#bbbbbb"}
    ]
}

Example request

curl https://api.seatsio.net/charts \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"name": "my chart"}'

Example response

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "tags": [],
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

Update a chart

The name and categories of a chart can be updated by posting to /charts/{chart key}.

POST /charts/{chartKey}
// PHP
$cat1 = ['key' => 1, 'label' => 'Category 1', 'color' => '#aaaaaa'];
$cat2 = ['key' => 2, 'label' => 'Category 2', 'color' => '#bbbbbb'];
$seatsioClient->charts->update("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "New name for my chart", [$cat1, $cat2])
// C#
var category1 = new Category(1, "Category 1", "#aaaaaa");
var category2 = new Category(2, "Category 2", "#bbbbbb");
var drawing = Client.Charts.Update("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "New name for my chart", new [] { category1, category2 });
// Java
Category category1 = new Category(1, "Category 1", "#aaaaaa");
Category category2 = new Category(2, "Category 2", "#bbbbbb");
client.charts.update("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "New name for my chart", Arrays.asList(category1, category2));
# Python
client.charts.update("4250fffc-e41f-c7cb-986a-2c5e728b8c28",
    new_name="New name for my chart", 
    categories=[
        {"key": 1, "label": "Category 1", "color": "#aaaaaa"}
    ])

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.

{
    "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:

{
    "categories": [
        { "key": 1, "label": "Category 1", "color": "#aaaaaa"},
        { "key": 2, "label": "Category 2", "color": "#bbbbbb"}
    ]
}

and you send this update chart request:

{
    "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.

{
    "categories": [
        { "key": 2, "label": "My category 2", "color": "#bbbbbb"}
    ]
}

Example request

curl https://api.seatsio.net/charts/4250fffc-e41f-c7cb-986a-2c5e728b8c28 \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"name": "New name for my chart"}'

Response

204 - No Content

Retrieve a chart thumbnail

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.

To use the thumbnail in an <img> tag, use the publicly accessible publishedVersionThumbnailUrl (or draftVersionThumbnailUrl) that is returned by the list charts and retrieve chart calls instead of the call documented below.

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.

Retrieve the published version thumbnail

GET /charts/{chartKey}/version/published/thumbnail

Note: this requires authentication by secret key. For a publicly available URL, use the publishedVersionThumbnailUrl that is returned by list charts and retrieve chart.

// PHP
$seatsioClient->charts->retrievePublishedVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// C#
Client.Charts.RetrievePublishedVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// Java
client.charts.retrievePublishedVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
# Python
client.charts.retrieve_published_version_thumbnail("749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl https://api.seatsio.net/charts/4250fffc-e41f-c7cb-986a-2c5e728b8c28/version/published/thumbnail \
-u aSecretKey:

Example response

Retrieve the draft version thumbnail

GET /charts/{chartKey}/version/draft/thumbnail

Note: this requires authentication by secret key. For a publicly available URL, use the draftVersionThumbnailUrl that is returned by list charts and retrieve chart.

// PHP
$seatsioClient->charts->retrieveDraftVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// C#
Client.Charts.RetrieveDraftVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// Java
client.charts.retrieveDraftVersionThumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
# Python
client.charts.retrieve_draft_version_thumbnail("4250fffc-e41f-c7cb-986a-2c5e728b8c28")

Example request

curl https://api.seatsio.net/charts/aChartKey/version/draft/thumbnail \
-u aSecretKey:

Example response

Error 404 (Not Found) is returned when the chart does not have a draft version.

Publish draft version

Publishing a draft version means replacing the currently published version by the draft version. The draft version is deleted afterwards. This cannot be undone!

POST /charts/{chartKey}/version/draft/actions/publish
// PHP
$seatsioClient->charts->publishDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// C#
Client.Charts.PublishDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// Java
client.charts.publishDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
# Python
client.charts.publish_draft_version("4250fffc-e41f-c7cb-986a-2c5e728b8c28")

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/version/draft/actions/publish \
-u aSecretKey:

Discard draft version

If you’re not happy with a draft version, you can choose to discard it. Discarding means deleting the draft version. This cannot be undone!

POST /charts/{chartKey}/version/draft/actions/discard
// PHP
$seatsioClient->charts->discardDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// C#
Client.Charts.DiscardDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
// Java
client.charts.discardDraftVersion("4250fffc-e41f-c7cb-986a-2c5e728b8c28");
# Python
client.charts.discard_draft_version("4250fffc-e41f-c7cb-986a-2c5e728b8c28")

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/version/draft/actions/discard \
-u aSecretKey:

List charts in the archive

When you don’t want a chart to show up on your dashboard, you have to move it to the archive. It will stay there forever, unless you decide to move it out of the archive again. Charts cannot be hard deleted.

GET /charts/archive
// PHP
$seatsioClient->charts->archive->all();
// C#
Client.Charts.Archive.ListAll();
// Java
client.charts.archive.all();
# Python
client.chats.archive.list()

Example

Example request

curl https://api.seatsio.net/charts/archive -u aSecretKey:

Example response

 {
    "next_page_starts_after": 12,
    "items":[
        {
            "name":"chart1",
            "id":"20",
            "key":"6451436c-24fb-11e7-93ae-92361f002671",
            "status":"PUBLISHED",
            "tags": [],
            "archived": true,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
        },
        {
            "name":"chart2",
            "id":"19",
            "key":"749b9650-24fb-11e7-93ae-92361f002671",
            "status":"NOT_USED",
            "tags": ["tag1", "tag2"],
            "archived": true,
            "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
        }
    ]
}

Move a chart to the archive

POST /charts/{chartKey}/actions/move-to-archive
// PHP
$seatsioClient->charts->moveToArchive("749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Charts.Archive.MoveToArchive("749b9650-24fb-11e7-93ae-92361f002671");
// Java
client.charts.moveToArchive("749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.charts.move_to_archive("749b9650-24fb-11e7-93ae-92361f002671")

Returns 204 when the chart was successfully moved to the archive. Returns 400 (Bad Request) when the chart was already moved to the archive.

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/actions/move-to-archive \
-u aSecretKey:

Move a chart out of the archive

POST /charts/{chartKey}/actions/move-out-of-archive
// PHP
$seatsioClient->charts->moveOutOfArchive("749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Charts.Archive.MoveOutOfArchive("749b9650-24fb-11e7-93ae-92361f002671");
// Java
client.charts.moveOutOfArchive("749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.charts.move_out_of_archive("749b9650-24fb-11e7-93ae-92361f002671")

Returns 204 when the chart was successfully moved out of the archive, back to the active chart list. Returns 400 (Bad Request) when the chart was not in the archive.

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/actions/move-out-of-archive \
-u aSecretKey:

Copy chart

Use this call to create a copy of a chart, based on the published chart version. The published version of the source chart is used as the published version of the new chart.

The chart name and tags are copied as well. The new chart name is not exactly the same as the old one though. We append “ (copy)” to the new chart name, e.g. “My Super Chart (copy)”.

Events linked to the original chart and the draft version are not copied.

The response contains 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.

POST /charts/{chartKey}/version/published/actions/copy
// PHP
$seatsioClient->charts->copy("749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Charts.Copy("749b9650-24fb-11e7-93ae-92361f002671");
// Java
client.charts.copy("749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.charts.copy("749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/version/published/actions/copy \
-u aSecretKey:

Example response

{
    "name":"chart2 (copy)",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "tags": ["tag1", "tag2"],
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

Copy chart from parent account to a subaccount

Use this call to copy a published chart version from the parent account to a subaccount. Events and tags linked to the original chart are not copied.

The response contains 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.

Note: look here for how to copy a chart from one subaccount to another.

POST /charts/{chartKey}/version/published/actions/copy-to/{subacountId}
// PHP
$seatsioClient->charts->copyToSubaccount("749b9650-24fb-11e7-93ae-92361f002671", 324);
// C#
Client.Charts.CopyToSubaccount("749b9650-24fb-11e7-93ae-92361f002671", 324);
// Java
client.charts.copyToSubaccount("749b9650-24fb-11e7-93ae-92361f002671", 324);
# Python
client.charts.copy_to_subaccount("749b9650-24fb-11e7-93ae-92361f002671", 324)

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/version/published/actions/copy-to/324 \
-u aSecretKey:

Example response

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "tags": [],
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

Copy draft version

Use this call to create a copy of a chart, based on the draft chart version. The draft version of the source chart is used as the published version of the new chart.

The chart name and tags are copied as well. The new chart name is not exactly the same as the old one though. We append “ (copy)” to the new chart name, e.g. “My Super Chart (copy)”.

Events linked to the original chart and the published version are not copied.

The response contains 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.

POST /charts/{chartKey}/version/draft/actions/copy
// PHP
$seatsioClient->charts->copyDraftVersion("749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Charts.CopyDraftVersion("749b9650-24fb-11e7-93ae-92361f002671");
// Java
client.charts.copyDraftVersion("749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.charts.copy_draft_version("749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl -X POST https://api.seatsio.net/charts/749b9650-24fb-11e7-93ae-92361f002671/version/draft/actions/copy \
-u aSecretKey:

Example response

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "tags": ["tag1", "tag2"],
    "archived": false,    
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

Chart tags

List tags of all charts

List all tags of all active (i.e. non-archived) charts.

GET /charts/tags
// PHP
$seatsioClient->charts->listAllTags();
// C#
Client.Charts.ListAllTags();
// Java
client.charts.listAllTags();
# Python
client.charts.client.charts.list_all_tags()

Example request

curl https://api.seatsio.net/charts/tags -u aSecretKey:

Example response

{
    "tags": ["tag1", "tag2", "tag3"]
}

Add a tag to a chart

POST /charts/{chartKey}/tags/{chartName}

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->charts->addTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
// C#
Client.Charts.AddTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
// Java
client.charts.addTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
# Python
client.charts.add_tag("749b9650-24fb-11e7-93ae-92361f002671", "tag1")

Example request

curl https://api.seatsio.net/charts/4250fffc-e41f-c7cb-986a-2c5e728b8c28/tags/tag1 \
-u aSecretKey: -X POST

Response

204 - No Content

Remove a tag from a chart

DELETE /charts/{chartKey}/tags/{chartName}

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->charts->removeTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
// C#
Client.Charts.RemoveTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
// Java
client.charts.removeTag("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "tag1");
# Python
client.charts.remove_tag("749b9650-24fb-11e7-93ae-92361f002671", "tag1")

Example request

curl https://api.seatsio.net/charts/4250fffc-e41f-c7cb-986a-2c5e728b8c28/tags/tag1 \
-u aSecretKey: -X DELETE

Response

204 - No Content

404 - Not Found: when the chart did not contain the tag you specified.

Events

List events

List non-deleted events, sorted by newest event first.

GET /events
// PHP
$seatsioClient->events->listFirstPage();
// C#
Client.Events.ListFirstPage();
// Java
client.events.listFirstPage();
# Python
client.events.list_first_page()

Example request

curl https://api.seatsio.net/events \
-u aSecretKey:

Example response

A paginated JSON object:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "key": "anEvent",
            "bookWholeTables": false,
            "chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28",
            "createdOn": "2017-05-05T10:58:44.715Z"
        },
        {
            "id": 168,
            "key": "anotherEvent",
            "bookWholeTables": true,
            "chartKey": "4150dddc-e41f-c7cb-986a-2c5e728b8c20",
            "createdOn": "2017-03-05T10:58:44.715Z",
            "updatedOn": "2017-04-05T10:58:44.615Z"
        }
        ...
    ]
}

Retrieve an event

GET /events/{eventKey}
// PHP
$seatsioClient->events->retrieve("anotherEvent");
// C#
Client.Events.Retrieve("anotherEvent");
// Java
client.events.retrieve("anotherEvent");
# Python
client.events.retrieve("anotherEvent")

Example request

curl https://api.seatsio.net/events/anEvent -u aSecretKey:

Example response

{
    "id": 168,
    "key": "anotherEvent",
    "bookWholeTables": true,
    "chartKey": "4150dddc-e41f-c7cb-986a-2c5e728b8c20",
    "supportsBestAvailable": true,
    "forSaleConfig": {
        "forSale": false,
        "objects": ["section1"],
        "categories": []
    },
    "createdOn": "2017-03-05T10:58:44.715Z",
    "updatedOn": "2017-04-05T10:58:44.615Z"
}

Create an event

POST /events
// PHP
$seatsioClient->events->create("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "event34", true);
// C#
Client.Events.Create("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "event34", true);
// Java
client.events.create("4250fffc-e41f-c7cb-986a-2c5e728b8c28", "event34", true);
# Python
client.events.create("749b9650-24fb-11e7-93ae-92361f002671", "event34")

Request

{
    "chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28",
    "eventKey": "event34",
    "bookWholeTables": true
}

Example request

curl https://api.seatsio.net/events \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28"}'

Example response

{
    "id": 169,
    "key": "anEvent",
    "chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28",
    "bookWholeTables": false,
    "supportsBestAvailable": true,
    "createdOn": "2017-05-05T10:58:44.715Z"
}

Update an event

POST /events/{eventKey}
// PHP
$seatsioClient->events->update("event34", "4250fffc-e41f-c7cb-986a-2c5e728b8c28", "newEventKey", true);
// C#
Client.Events.Update("event34", "4250fffc-e41f-c7cb-986a-2c5e728b8c28", "newEventKey", true);
// Java
client.events.update("event34", "4250fffc-e41f-c7cb-986a-2c5e728b8c28", "newEventKey", true);
# Python
client.events.update("event34", chart_key="4250fffc-e41f-c7cb-986a-2c5e728b8c28", event_key="newEventKey")

Request

{
    "chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28",
    "eventKey": "newEventKey",
    "bookWholeTables": true
}

All fields are optional. If for example you don’t specify an eventKey, the key of the event is not modified.

Example request

curl https://api.seatsio.net/events/event34 \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"chartKey": "4250fffc-e41f-c7cb-986a-2c5e728b8c28"}'

Response

204 - No Content

Delete an event

DELETE /events/{eventKey}
// PHP
$seatsioClient->events->delete("event34");
// C#
Client.Events.Delete("event34");
// Java
client.events.delete("event34");
# Python
client.events.delete("event34")

Example request

curl https://api.seatsio.net/events/event34 \
-u aSecretKey: -X DELETE -H 'Content-Type: application/json'

Response

204 - No Content

List events for a chart

See the charts chapter. It comes down to retrieving the chart with the expand=events query parameter.

Update extra data for an object

Updates the extra data for an object in an event, without changing the object status.

POST /events/{eventKey}/objects/{objectLabel}/actions/update-extra-data

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->events->updateExtraData("event34", "A-1", ["name" => "John Doe"]);
// C#
var extraData = new Dictionary<string, object> {{ "name", "John Doe" }};
Client.Events.UpdateExtraData("event34", "A-1", extraData);
// Java
Map<?, ?> extraData = new HashMap<>();
extraData.put("name", "John Doe");
client.events.updateExtraData("event34", "A-1", extraData);
# Python
extra_data = {"name": "John Doe"}
client.events.update_extra_data("event34", "A-1", extra_data)

Request

{
    "extraData": {
        "name": "John Doe"
    }
}

extraData must be a valid JSON object.

Example request

curl https://api.seatsio.net/events/event34/objects/A-1/actions/update-extra-data \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"extraData": {"name": "John Doe"}}'

Response

204 - No Content

Retrieve the status of an object

GET /events/{eventKey}/objects/{objectLabel}

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->events->getObjectStatus("event34", "A-1");
// C#
Client.Events.GetObjectStatus("event34", "A-1");
// Java
client.events.getObjectStatus("event34", "A-1");
# Python
client.events.retrieve_object_status("event34", "A-1")

Example request

curl https://api.seatsio.net/event34/objects/A-1 -u aSecretKey:

Example response

Regular, non-GA object:

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

When the object is held (status reservedByToken), there’s an additional property holdToken which is the hold token string that was used to hold the object.

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.

List status changes

Each time the status of an object changes (e.g. by booking or releasing it), a status change is added to seats.io. Use the following API call to list the status changes for an event.

Status changes are returned paginated, with the most recent ones first.

GET /events/{eventKey}/status-changes
// PHP
$seatsioClient->events->statusChanges("event34")->firstPage();
// C#
Client.Events.StatusChanges("event34").FirstPage();
// Java
client.events.statusChanges("event34").firstPage();
# Python
client.events.list_status_changes("event34").first_page()

Example request

curl https://api.seatsio.net/events/anEvent/status-changes?limit=100&start_after_id=34 \
-u aSecretKey:

Example response

A paginated JSON object that contains the status changes in the event:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "eventId": 12,
            "status": "booked",
            "quantity": 1,
            "objectLabel": "A-1",
            "date": "2017-05-05T10:58:44.715Z",
            "orderId": "anOrder",
            "extraData": {
                "name": "John Doe"
            }
        },
        {
            "id": 168,
            "eventId": 12,
            "status": "free",
            "quantity": 1,
            "objectLabel": "B-1",
            "date": "2017-05-05T09:58:44.715Z",
            "orderId": "anotherOrder",
            "extraData": {
                "name": "Jane Doe"
            }
        }
        ...
    ]
}

List status changes for an object

Lists status changes for an object in the event, with the most recent ones first.

GET /events/{eventKey}/objects/{objectLabel}/status-changes
// PHP
$seatsioClient->events->statusChanges("event34", "A-1")->firstPage();
// C#
Client.Events.StatusChanges("event34", "A-1").FirstPage();
// Java
client.events.statusChanges("event34", "A-1").firstPage();
# Python
client.events.list_status_changes("event34", "A-1").first_page()

Example request

curl https://api.seatsio.net/events/event34/objects/A-1/status-changes?limit=100&start_after_id=34 \
-u aSecretKey:

Example response

A paginated JSON object:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "eventId": 12,
            "status": "booked",
            "quantity": 1,
            "objectLabel": "A-1",
            "date": "2017-05-05T10:58:44.715Z",
            "orderId": "anOrder",
            "extraData": {
                "name": "John Doe"
            }
        },
        {
            "id": 168,
            "eventId": 12,
            "status": "free",
            "quantity": 1,
            "objectLabel": "A-1",
            "date": "2017-05-05T09:58:44.715Z",
            "orderId": "anotherOrder",
            "extraData": {
                "name": "Jane Doe"
            }
        }
        ...
    ]
}

Event reports

Detailed reports

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

GET /reports/events/{eventKey}/{reportType}

The report types you can choose from are:
- byStatus
- byCategoryLabel
- byCategoryKey
- byLabel
- byOrderId
- bySection

You can also pass in an optional filter, for example to retrieve only the objects in a certain status:

GET /reports/events/{eventKey}/{reportType}/{filter}

E.g. /reports/events/event34/byStatus/booked

Detailed report by status

GET /reports/events/{eventKey}/byStatus
GET /reports/events/{eventKey}/byStatus/{status}

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->eventReports->byStatus("event34");
$seatsioClient->eventReports->byStatus("event34", "booked");
// C#
Client.EventReports.ByStatus("event34");
Client.EventReports.ByStatus("event34", "booked");
// Java
client.eventReports.byStatus("event34");
client.eventReports.byStatus("event34", "booked");
# Python
client.events.reports.by_status("event34")
client.events.reports.by_status("event34", status="booked")

Example request

curl https://api.seatsio.net/reports/events/event34/byStatus -u aSecretKey:

Example response

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

Detailed report by category label

GET /reports/events/{eventKey}/byCategoryLabel
GET /reports/events/{eventKey}/byCategoryLabel/{categoryLabel}
GET /reports/events/{eventKey}/byCategoryLabel/NO_CATEGORY

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->eventReports->byCategoryLabel("event34");
$seatsioClient->eventReports->byCategoryLabel("event34", "cat1");
$seatsioClient->eventReports->byCategoryLabel("event34", "NO_CATEGORY");
// C#
Client.EventReports.ByCategoryLabel("event34");
Client.EventReports.ByCategoryLabel("event34", "cat1");
Client.EventReports.ByCategoryLabel("event34", "NO_CATEGORY");
// Java
client.eventReports.byCategoryLabel("event34");
client.eventReports.byCategoryLabel("event34", "cat1");
client.eventReports.byCategoryLabel("event34", "NO_CATEGORY");
# Python
client.events.reports.by_category_label("event34")
client.events.reports.by_category_label("event34", "category1")
client.events.reports.by_category_label("event34", "NO_CATEGORY")

Example request

curl https://api.seatsio.net/reports/events/event34/byCategoryLabel -u aSecretKey:

Example response

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

Detailed report by category key

GET /reports/events/{eventKey}/byCategoryKey
GET /reports/events/{eventKey}/byCategoryKey/{categoryKey}
GET /reports/events/{eventKey}/byCategoryKey/NO_CATEGORY
// PHP
$seatsioClient->eventReports->byCategoryKey("event34");
$seatsioClient->eventReports->byCategoryKey("event34", "4");
$seatsioClient->eventReports->byCategoryKey("event34", "NO_CATEGORY");
// C#
Client.EventReports.ByCategoryKey("event34");
Client.EventReports.ByCategoryKey("event34", "4");
Client.EventReports.ByCategoryKey("event34", "NO_CATEGORY");
// Java
client.eventReports.byCategoryKey("event34");
client.eventReports.byCategoryKey("event34", "4");
client.eventReports.byCategoryKey("event34", "NO_CATEGORY");
# Python
client.events.reports.by_category_key("event34")
client.events.reports.by_category_key("event34", "4")
client.events.reports.by_category_key("event34", "NO_CATEGORY")

Example request

curl https://api.seatsio.net/reports/events/event34/byCategoryKey -u aSecretKey:

Example response

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

Detailed report by label

GET /reports/events/{eventKey}/byLabel
GET /reports/events/{eventKey}/byLabel/{label}

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->eventReports->byLabel("event34");
$seatsioClient->eventReports->byLabel("event34", "C-11");
// C#
Client.EventReports.ByLabel("event34");
Client.EventReports.ByLabel("event34", "C-11");
// Java
client.eventReports.byLabel("event34");
client.eventReports.byLabel("event34", "C-11");
# Python
client.events.reports.by_label("event34")
client.events.reports.by_label("event34", "C-11")

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

Example request

curl https://api.seatsio.net/reports/events/event34/byLabel -u aSecretKey:

Example response

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

Detailed report by order id

GET /reports/events/{eventKey}/byOrderId
GET /reports/events/{eventKey}/byOrderId/{orderId}
GET /reports/events/{eventKey}/byOrderId/NO_ORDER_ID
// PHP
$seatsioClient->eventReports->byOrderId("event34");
$seatsioClient->eventReports->byOrderId("event34", "order1");
$seatsioClient->eventReports->byOrderId("event34", "NO_ORDER_ID");
// C#
Client.EventReports.ByOrderId("event34");
Client.EventReports.ByOrderId("event34", "order1");
Client.EventReports.ByOrderId("event34", "NO_ORDER_ID");
// Java
client.eventReports.byOrderId("event34");
client.eventReports.byOrderId("event34", "order1");
client.eventReports.byOrderId("event34", "NO_ORDER_ID");
# Python
client.events.reports.by_order_id("event34")
client.events.reports.by_order_id("event34", "order1")
client.events.reports.by_order_id("event34", "NO_ORDER_ID")

Example request

curl https://api.seatsio.net/reports/events/event34/byOrderId -u aSecretKey:

Example response

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

Detailed report by section

GET /reports/events/{eventKey}/bySection
GET /reports/events/{eventKey}/bySection/{section}
GET /reports/events/{eventKey}/bySection/NO_SECTION

Keep in mind that certain characters need to be encoded.

// PHP
$seatsioClient->eventReports->bySection("event34");
$seatsioClient->eventReports->bySection("event34", "Floor");
$seatsioClient->eventReports->bySection("event34", "NO_SECTION");
// C#
Client.EventReports.BySection("event34");
Client.EventReports.BySection("event34", "Floor");
Client.EventReports.BySection("event34", "NO_SECTION");
// Java
client.eventReports.bySection("event34");
client.eventReports.bySection("event34", "Floor");
client.eventReports.bySection("event34", "NO_SECTION");
# Python
client.events.reports.by_section("event34")
client.events.reports.by_section("event34", "Floor")
client.events.reports.by_section("event34", "NO_SECTION")

Example request

curl https://api.seatsio.net/reports/events/event34/bySection -u aSecretKey:

Example response

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

Summary reports

Summary reports are a … summarized … version of the detailed event reports. They indicate how many objects are in a certain status, category or section.

They also allow you to drill down into the numbers: how many booked seats are there in category A? how many free seats are left in section B?

Summary report by status

GET /reports/events/{eventKey}/byStatus/summary
// PHP
$seatsioClient->eventReports->summaryByStatus("event34");
// C#
Client.EventReports.SummaryByStatus("event34");
// Java
client.eventReports.summaryByStatus("event34");
# Python
client.events.reports.summary_by_status("event34")

Example request

curl https://api.seatsio.net/reports/events/event34/byStatus/summary -u aSecretKey:

Example response

{
    "booked": {
        "count": 34,
        "bySection": {
            "Floor": 12,
            "Balcony": 22
        },
        "byCategoryLabel": {
            "premium": 10,
            "standard": 24
        },
        "byCategoryKey": {
            "1": 10,
            "2": 24
        }
    },
    "free": {
        "count": 80,
        "bySection": {
            "Balcony": 80
        },
        "byCategoryLabel": {
            "premium": 2,
            "standard": 78
        },
        "byCategoryKey": {
            "1": 2,
            "2": 78
        }
    }
}

Summary report by category label

GET /reports/events/{eventKey}/byCategoryLabel/summary
// PHP
$seatsioClient->eventReports->summaryByCategoryLabel("event34");
// C#
Client.EventReports.SummaryByCategoryLabel("event34");
// Java
client.eventReports.summaryByCategoryLabel("event34");
# Python
client.events.reports.summary_by_category_label("event34")

Example request

curl https://api.seatsio.net/reports/events/event34/byCategoryLabel/summary -u aSecretKey:

Example response

{
    "premium": {
        "count": 34,
        "bySection": {
            "Floor": 12,
            "Balcony": 22
        },
        "byStatus": {
            "free": 10,
            "booked": 24
        }
    },
    "standard": {
        "count": 80,
        "bySection": {
            "Balcony": 80
        },
        "byStatus": {
            "free": 2,
            "booked": 78
        }
    },
    "NO_CATEGORY": {
        "count": 0,
        "bySection": {},
        "byStatus": {}
    }
}

Summary report by category key

GET /reports/events/{eventKey}/byCategoryKey/summary
// PHP
$seatsioClient->eventReports->summaryByCategoryKey("event34");
// C#
Client.EventReports.SummaryByCategoryKey("event34");
// Java
client.eventReports.summaryByCategoryKey("event34");
# Python
client.events.reports.summary_by_category_key("event34")

Example request

curl https://api.seatsio.net/reports/events/event34/byCategoryKey/summary -u aSecretKey:

Example response

{
    "1": {
        "count": 34,
        "bySection": {
            "Floor": 12,
            "Balcony": 22
        },
        "byStatus": {
            "free": 10,
            "booked": 24
        }
    },
    "2": {
        "count": 80,
        "bySection": {
            "Balcony": 80
        },
        "byStatus": {
            "free": 2,
            "booked": 78
        }
    },
    "NO_CATEGORY": {
        "count": 0,
        "bySection": {},
        "byStatus": {}
    }
}

Summary report by section

GET /reports/events/{eventKey}/bySection/summary
// PHP
$seatsioClient->eventReports->summaryBySection("event34");
// C#
Client.EventReports.SummaryBySection("event34");
// Java
client.eventReports.summaryBySection("event34");
# Python
client.events.reports.summary_by_section("event34")

Example request

curl https://api.seatsio.net/reports/events/event34/bySection/summary -u aSecretKey:

Example response

{
    "Floor": {
        "count": 34,
        "byStatus": {
            "booked": 12,
            "free": 22
        },
        "byCategoryLabel": {
            "premium": 10,
            "standard": 24
        },
        "byCategoryKey": {
            "1": 10,
            "2": 24
        }
    },
    "Balcony": {
        "count": 80,
        "byStatus": {
            "free": 80
        },
        "byCategoryLabel": {
            "premium": 2,
            "standard": 78
        },
        "byCategoryKey": {
            "1": 2,
            "2": 78
        }
    },
    "NO_SECTION": {
        "count": 0,
        "byStatus": {},
        "byCategoryLabel": {},
        "byCategoryKey": {}
    }
}

Hold Tokens

Seats.io uses so-called hold tokens to keep track of objects that are temporarily held (i.e. marking a seat as unavailable for a short while, until the person who selected it completes the ticket buying process).
These hold tokens are the combination of a UUID and an expiration time, and they are stored on the seats.io server until they expire. When they expire, all associated held objects are automatically released.

Under normal circumstances, such a hold token is generated by the user’s browser, when it renders a floor plan that has holdOnSelect: true.
However, you can also generate hold tokens programatically. This is useful when book best available seats via the seats.io API instead of showing a floor plan to your ticket buyers, but still want to take advantage of temporarily holding objects.

The hold token object

Attributes

Retrieve a hold token

GET /hold-tokens/{token}
// PHP
$seatsioClient->holdTokens->retrieve("18725661-36d6-4755-905a-28ce82d0c2d5");
// C#
Client.HoldTokens.Retrieve("18725661-36d6-4755-905a-28ce82d0c2d5");
// Java
client.holdTokens.retrieve("18725661-36d6-4755-905a-28ce82d0c2d5");
# Python
client.hold_tokens.retrieve("18725661-36d6-4755-905a-28ce82d0c2d5")

Example request

curl https://api.seatsio.net/hold-tokens/18725661-36d6-4755-905a-28ce82d0c2d5 \
-u aSecretKey:

Example response

A JSON object that represents the hold token:

{
    "holdToken": "18725661-36d6-4755-905a-28ce82d0c2d5",
    "expiresAt": "2017-05-05T10:58:44.715Z"
}

Error 404 (Not Found) is returned when the hold token does not exist.

Create a hold token

POST /hold-tokens
// PHP
$seatsioClient->holdTokens->create();
// C#
Client.HoldTokens.Create();
// Java
client.holdTokens.create();
# Python
client.hold_tokens.create()

Example request

curl -X POST https://api.seatsio.net/hold-tokens \
-u aSecretKey:

Example response

{    
    "holdToken": "71f0fc20-3c3b-4f9f-a38b-ed350ba564e7",
    "expiresAt": "2017-05-05T10:58:44.715Z"
}

Change expiration date

Once a hold token is created, you can change its validity period.
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 hold token is 2 hours. That means that a token that was created 10 minutes ago can at most be valid for another 1h50m.

POST /hold-tokens/{token}
// PHP
$seatsioClient->holdTokens->expireInMinutes("a6ec0bc0-4c43-11e7-b114-b2f933d5fe66", 30);
// C#
Client.HoldTokens.ExpireInMinutes("a6ec0bc0-4c43-11e7-b114-b2f933d5fe66", 30);
// Java
client.holdTokens.expireInMinutes("a6ec0bc0-4c43-11e7-b114-b2f933d5fe66", 30);
# Python
client.hold_tokens.expire_in_minutes("18725661-36d6-4755-905a-28ce82d0c2d5", 30)

To change the expiration date of hold token, send a POST to https://api.seatsio.net/hold-tokens/{token}. The request body must be a JSON object containing an expiresInMinutes property:

{
  expiresInMinutes: 30
}

Example request

curl -X POST https://api.seatsio.net/hold-tokens/a6ec0bc0-4c43-11e7-b114-b2f933d5fe66 \
-u aSecretKey: \
-H "Content-Type: application/json" \
-d "{'expiresInMinutes': 30}"

Example response

 {    
     "holdToken": "a6ec0bc0-4c43-11e7-b114-b2f933d5fe66",
     "expiresAt": "2017-05-05T10:58:44.715Z"
 }

Subaccounts

The seats.io API lets you create and list subaccounts. 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.

List all subaccounts

Returns a paginated list of subaccounts you’ve previously created. The subaccounts are returned in reverse chronological order: the most recently created subaccounts will appear first in the list.

Both active and inactive subaccounts are returned.

GET /subaccounts
// PHP
$seatsioClient->subaccounts->listFirstPage();
// C#
Client.Subaccounts.ListFirstPage();
// Java
client.subaccounts.listFirstPage();
# Python
client.subaccounts.list().first_page()

Example request

curl https://api.seatsio.net/subaccounts?limit=100&start_after_id=34 \
-u aSecretKey:

Example response

A paginated JSON object that contains the subaccounts of the authenticated user:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "secretKey": "7c647eed-0880-4118-9459-82757579703e",
            "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005",
            "publicKey": "18725661-36d6-4755-905a-28ce82d0c2d5",
            "active": true,
            "name": "a subaccount"
        },
        {
            "id": 170,
            "secretKey": "2d59a6ce-cd43-406a-b49d-fcb0a88416ad",
            "designerKey": "e1c9be75-2052-41b5-ad6c-2986a6d7ee85",
            "publicKey": "81c32887-c014-43ac-90cb-f8db613d5643",
            "active": false,
            "name": "another subaccount"
        }
        ...
    ]
}

List active subaccounts

Returns a paginated list of active subaccounts.

GET /subaccounts/active
// PHP
$seatsioClient->subaccounts->active->firstPage();
// C#
Client.Subaccounts.Active.FirstPage();
// Java
client.subaccounts.active.firstPage();
# Python
client.subaccounts.active.list().first_page()

Example request

curl https://api.seatsio.net/subaccounts/active?limit=100&start_after_id=34 \
-u aSecretKey:

Example response

A paginated JSON object that contains the active subaccounts of the authenticated user:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "secretKey": "7c647eed-0880-4118-9459-82757579703e",
            "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005",
            "publicKey": "18725661-36d6-4755-905a-28ce82d0c2d5",
            "active": true
        },
        {
            "id": 170,
            "secretKey": "2d59a6ce-cd43-406a-b49d-fcb0a88416ad",
            "designerKey": "e1c9be75-2052-41b5-ad6c-2986a6d7ee85",
            "publicKey": "81c32887-c014-43ac-90cb-f8db613d5643",
            "active": true
        }
        ...
    ]
}

List inactive subaccounts

Returns a paginated list of inactive subaccounts.

GET /subaccounts/inactive
// PHP
$seatsioClient->subaccounts->inactive->firstPage();
// C#
Client.Subaccounts.Inactive.FirstPage();
// Java
client.subaccounts.inactive.firstPage();
# Python
client.subaccounts.inactive.list().first_page()

Example request

curl https://api.seatsio.net/subaccounts/inactive?limit=100&start_after_id=34 \
-u aSecretKey:

Example response

A paginated JSON object that contains the inactive subaccounts of the authenticated user:

{
    "next_page_starts_after": 122,
    "items": [
        {
            "id": 169,
            "secretKey": "7c647eed-0880-4118-9459-82757579703e",
            "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005",
            "publicKey": "18725661-36d6-4755-905a-28ce82d0c2d5",
            "active": false
        },
        {
            "id": 170,
            "secretKey": "2d59a6ce-cd43-406a-b49d-fcb0a88416ad",
            "designerKey": "e1c9be75-2052-41b5-ad6c-2986a6d7ee85",
            "publicKey": "81c32887-c014-43ac-90cb-f8db613d5643",
            "active": false
        }
        ...
    ]
}

Retrieve a subaccount

GET /subaccounts/{id}
// PHP
$seatsioClient->subaccounts->retrieve(169);
// C#
Client.Subaccounts.Retrieve(169);
// Java
client.subaccounts.retrieve(169);
# Python
client.subaccounts.retrieve(169)

Example request

curl https://api.seatsio.net/subaccounts/169 \
-u aSecretKey:

Example response

A JSON object that represents the subaccount:

{
    "id": 169,
    "secretKey": "7c647eed-0880-4118-9459-82757579703e",
    "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005",
    "publicKey": "18725661-36d6-4755-905a-28ce82d0c2d5",
    "name": "a subaccount",
    "active": true
}

Error 404 (Not Found) is returned when the subaccount does not exist (or when it belongs to another parent user)

Create a subaccount

Creates a subaccount with an e-mail address and a name. Both the e-mail and the name are optional.

If you do pass in an e-mail, the subaccount receives a message with a link to set the initital password. From that point on, he can log in at the dashboard https://app.seats.io to manage charts and events.

POST /subaccounts
// PHP
$seatsioClient->subaccounts->createWithEmail("jeff@test.com", "a subaccount");
$seatsioClient->subaccounts->create("a subaccount");
// C#
Client.Subaccounts.CreateWithEmail("jeff@test.com", "a subaccount);
Client.Subaccounts.Create("a subaccount);
// Java
client.subaccounts.createWithEmail("jeff@test.com", "a subaccount");
client.subaccounts.create("a subaccount");
# Python
client.subaccounts.create_with_email("jeff@test.com", "a subaccount")
client.subaccounts.create("a subaccount")

Request

{
    "email": "jeff@test.com",
    "name": "a subaccount"
}

Example request

curl -X POST https://api.seatsio.net/subaccounts \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"email": "jeff@test.com", "name": "a subaccount"}'

Example response

{
    "id": 169,
    "secretKey": "7c647eed-0880-4118-9459-82757579703e",
    "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005",
    "publicKey": "18725661-36d6-4755-905a-28ce82d0c2d5",
    "active": true,
    "email": "jeff@test.com",
    "name": "a subaccount"
}

Update a subaccount

POST /subaccounts/{id}
// PHP
$seatsioClient->subaccounts->update("a new subaccount name", "jeff@test.com");
// C#
Client.Subaccounts.Update("a new subaccount name", "jeff@test.com");
// Java
client.subaccounts.update("a new subaccount name", "jeff@test.com");
# Python
client.subaccounts.update(169, "a new subaccount name", "jeff@test.com")

Request

{
    "name": "a new subaccount name",
    "email": "jeff@test.com"
}

Example request

curl -X POST https://api.seatsio.net/subaccounts/34 \
-u aSecretKey: -X POST -H 'Content-Type: application/json' -d '{"name": "a new subaccount name", "email", "jeff@test.com"}'

Response

204 - No Content

Copy chart from a subaccount to other subaccount or to parent

Use this call to copy a published chart version from a subaccount to another subaccount or to your parent account.

subaccountIdOrParent is either the ID of the subaccount to copy to, or the string ‘parent’.

Events and tags linked to the original chart are not copied.

The response contains 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.

Note: look here for how to copy a chart from the parent account to a subaccount.

POST /subaccounts/{id}/charts/{chartKey}/actions/copy-to/{subaccountIdOrParent}
// PHP
$seatsioClient->subaccounts->copyChartToParent(312, "749b9650-24fb-11e7-93ae-92361f002671");
$seatsioClient->subaccounts->copyChartToSubaccount(312, 324, "749b9650-24fb-11e7-93ae-92361f002671");
// C#
Client.Subaccounts.CopyChartToParent(312, "749b9650-24fb-11e7-93ae-92361f002671");
Client.Subaccounts.CopyChartToSubaccount(312, 324, "749b9650-24fb-11e7-93ae-92361f002671");
// Java
client.subaccounts.copyChartToParent(312, "749b9650-24fb-11e7-93ae-92361f002671");
client.subaccounts.copyChartToSubaccount(312, 324, "749b9650-24fb-11e7-93ae-92361f002671");
# Python
client.subaccounts.copy_chart_to_parent(312, "749b9650-24fb-11e7-93ae-92361f002671")
client.subaccounts.copy_chart_to_subaccount(312, 324, "749b9650-24fb-11e7-93ae-92361f002671")

Example request

curl -X POST https://api.seatsio.net/subaccounts/312/charts/749b9650-24fb-11e7-93ae-92361f002671/actions/copy-to/324 \
-u aSecretKey:

Example response

{
    "name":"chart2",
    "id":"19",
    "key":"749b9650-24fb-11e7-93ae-92361f002671",
    "status":"NOT_USED",
    "tags": [],
    "archived": false,
    "publishedVersionThumbnailUrl": "https://cdn.seats.io/system/public/.../published/.../thumbnail"
}

Deactivate a subaccount

Subaccounts are either active or inactive. Inactive subaccounts do not have the permission to create charts, create events, book seats … or frankly, to do anything meaningful.

POST /subaccounts/{id}/actions/deactivate
// PHP
$seatsioClient->subaccounts->deactivate(169);
// C#
Client.Subaccounts.Deactivate(169);
// Java
client.subaccounts.deactivate(169);
# Python
client.subaccounts.deactivate(169)

Example request

curl -X POST https://api.seatsio.net/subaccounts/169/actions/deactivate \
-u aSecretKey:

Response

204 - No Content

Activate a subaccount

POST /subaccounts/{id}/actions/activate
// PHP
$seatsioClient->subaccounts->activate(169);
// C#
Client.Subaccounts.Activate(169);
// Java
client.subaccounts.activate(169);
# Python
client.subaccounts.activate(169)

Example request

curl -X POST https://api.seatsio.net/subaccounts/169/actions/activate \
-u aSecretKey:

Response

204 - No Content

Regenerate the secret key

The secret key of a subaccount should be kept secret at all times. If it does get compromised, you can generate a new one.

POST /subaccounts/{id}/secret-key/actions/regenerate
// PHP
$seatsioClient->subaccounts->regenerateSecretKey(169);
// C#
Client.Subaccounts.RegenerateSecretKey(169);
// Java
client.subaccounts.regenerateSecretKey(169);
# Python
client.subaccounts.regenerate_secret_key(169)

Example request

curl -X POST https://api.seatsio.net/subaccounts/169/secret-key/actions/regenerate \
-u aSecretKey:

Example response

{
    "secretKey": "7c647eed-0880-4118-9459-82757579703e"
}

Regenerate the designer key

The designer key of a subaccount should be kept secret at all times. If it does get compromised, you can generate a new one.

POST /subaccounts/{id}/designer-key/actions/regenerate
// PHP
$seatsioClient->subaccounts->regenerateDesignerKey(169);
// C#
Client.Subaccounts.RegenerateDesignerKey(169);
// Java
client.subaccounts.regenerateDesignerKey(169);
# Python
client.subaccounts.regenerate_designer_key(169)

Example request

curl -X POST https://api.seatsio.net/subaccounts/169/designer-key/actions/regenerate \
-u aSecretKey:

Example response

{
    "designerKey": "88cd2f93-2e82-489e-a10d-d68413f7d005"
}