API reference

Last updated 14 October 2026

The Advance API lets a venue's website, ticketing, screens or spreadsheets read the same show information the venue's team works from. It is read-only: nothing can be changed through it.

Getting a key

A venue admin creates keys in The Advance under Settings → API (API access is switched on per venue; ask hello@theadvance.co.uk). The key is shown once, so copy it then. Each key is one of two kinds:

Public: for anything the public sees, such as a website's gig listings. Show titles, dates, rooms, times and acts.
Private: for the venue's own tools. Also crew names, ticket sales and advance status. Keep it out of web pages and shared documents.

Deal notes, contacts, phone numbers, rates and files are never available through the API. A key can be revoked at any time in Settings → API, and stops working straight away.

Making a request

Send the key in the Authorization header. Every response is JSON with the result in data.

curl -H "Authorization: Bearer tadv_…" https://app.theadvance.co.uk/api/v1/rooms

Call the API from a server, your website's back end or a scheduled job, not from visitors' browsers: browsers can't call it directly, and a key in a web page can be copied. Show information changes a few times a day at most, so cache it and refresh every few minutes rather than on every page view.

GET /rooms

The venue's active rooms.

{
  "data": [
    { "code": "L1", "name": "Main room", "address": "…", "capacity": 450 },
    { "code": "L2", "name": "Studio", "address": "…", "capacity": 150 }
  ]
}

GET /shows

Shows in a date range, earliest first. Without from and to you get today and the next 90 days.

curl -H "Authorization: Bearer tadv_…" \
  "https://app.theadvance.co.uk/api/v1/shows?from=2026-11-01&to=2026-11-30"

from: first date, yyyy-mm-dd (default today)
to: last date, yyyy-mm-dd (default 90 days after from)

With a public key:

{
  "data": [
    {
      "id": 412,
      "title": "The Paper Lanterns",
      "date": "2026-11-14",
      "status": "scheduled",
      "room": { "code": "L1", "name": "Main room" },
      "schedule": [
        { "label": "Doors", "time": "19:00" },
        { "label": "Folk Night (30 mins)", "time": "19:45" },
        { "label": "The Paper Lanterns (75 mins)", "time": "20:30" },
        { "label": "Curfew", "time": "23:00" }
      ],
      "acts": [
        { "name": "The Paper Lanterns", "billing": "headliner", "setTime": "20:30", "setLengthMinutes": 75 },
        { "name": "Folk Night", "billing": "support", "setTime": "19:45", "setLengthMinutes": 30 }
      ],
      "capacity": 450,
      "updatedAt": "2026-10-12T15:04:11.000Z"
    }
  ]
}

A private key also gets:

      "advanceStatus": "ready",
      "promoterType": "external",
      "crew": [
        { "position": "Sound", "name": "Sam Sound", "status": "confirmed" },
        { "position": "Lighting", "name": "Lee Lights", "status": "offered" }
      ],
      "ticketsSold": 312

GET /shows/:id

One show, in the same shape as above. Shows from any date can be fetched by id. Returns 404 if there's no such show at the venue.

curl -H "Authorization: Bearer tadv_…" https://app.theadvance.co.uk/api/v1/shows/412

Show fields

Field	Type	What it is	Keys
`id`	number	The show's id. Stable: use it to match shows between calls.	all
`title`	string	The show's name, e.g. “The Paper Lanterns + Folk Night”.	all
`date`	string	The show date, yyyy-mm-dd. Times after midnight still belong to this date.	all
`status`	string	“scheduled”, “cancelled” or “postponed”.	all
`room`	object	Which room: { code, name }, e.g. { “L1”, “Main room” }.	all
`schedule`	array	The running order: [{ label, time }], times as HH:MM (UK time), in order. Labels are the venue's, e.g. “Doors”, “Curfew”.	all
`acts`	array	[{ name, billing, setTime, setLengthMinutes }]. billing is “headliner” or “support”; setTime is HH:MM or empty.	all
`capacity`	number \| null	Capacity for this show.	all
`updatedAt`	string	When anything on the show last changed (ISO 8601).	all
`advanceStatus`	string	How far the venue's advance has got: “provisional”, “ready”, “cancelled” or “postponed”.	private only
`promoterType`	string	“venue” (the venue's own show), “external” (a promoter) or “hire”.	private only
`crew`	array	[{ position, name, status }] for crew offered or confirmed. status is “offered” or “confirmed”.	private only
`ticketsSold`	number \| null	Tickets sold, as last recorded by the venue.	private only

Fields with nothing recorded are null or empty. All times are UK local time (Europe/London).

Errors

Errors come back as { "error": "…" } with a plain-English message:

401: the key is missing, mistyped or revoked.
403: API access isn't switched on for this venue, or the venue's account is paused.
404: no such show.

Changes

This is version 1 (/api/v1). New fields may be added to responses, so ignore any you don't recognise. Existing fields won't be renamed, removed or change meaning within version 1; anything that would is a new version, announced in advance.