API guide

What it is

An API you can only read from. Writing, changing or deleting is not possible. Every key belongs to one organisation and sees only that organisation's data. Where that boundary lies is not an agreement in our code that someone could forget: every request goes through the database, which checks the key and returns only rows of that organisation.

There are two kinds of key:

• Full key, starts with ub_live_. For a connection with a CRM, an accountant or your own software. Never put it in a website. It needs the API in your plan: that is included in Ultimate Artist and Ultimate Agency. With Artist and Agency you can add it for €15.00 per month excl. VAT.
• Website key, starts with ub_web_. Free in every plan. It only returns your public shows (date, venue, city, country, artist) and can therefore safely sit in the code of your website.

Creating a key

1. In Ultimate Bookings, go to Instellingen, API-sleutels (Settings, API keys). Only the owner of the organisation can create, pause and delete keys here.
2. Give the key a name (up to 80 characters), for example Website or CRM.
3. Choose the kind: website key or full key.
4. For a full key, tick what it may read: Shows (always on), Agenda, Contacten (contacts), Artiesten (artists) and Geld (money). Money is off by default: only once you tick it does the key see fees and invoices.
5. Choose Sleutel maken (create key). The key is then shown once. Copy it straight away. We only store a derived value (a hash), so we cannot show it to you again. Lost it? Delete it and create a new one.

You can pause a key: it stops working immediately and you can switch it back on later. Deleting is permanent. The list shows for each key when it was last used and how often.

A show only appears for the website key once you have ticked Op je website tonen (show on your website) yourself in the booking form. It is off by default, so a private party or an option (hold) never becomes public by itself.

Authenticating with your key

Send the key in the header of every request:

Authorization: Bearer ub_live_YOUR_KEY

A website key may also go in the address, as ?sleutel=ub_web_... (sleutel means key). That is meant for a browser: this source can be reached from any website (CORS is open), so you can fetch directly from your own page. This only works for openbare-shows. A full key in the address is ignored; it must always go in the header and belongs on a server only.

The six sources

All addresses are GET and start with https://ultimate-bookings.com/api/v1. A full key needs the permission listed; every full key has Shows. Fields without a value are left out of the response instead of being null.

Parameters

• van (from) and tot (to): a date like 2026-10-01, in Amsterdam time. Both days count. For shows and agenda this is the start time, for invoices the invoice date.
• limiet (limit): how many rows at a time, a whole number from 1 to 500. Default 100.
• vanaf (offset): how many rows to skip, for the next page. Default 0.

A parameter that a source does not use is still checked for validity, but otherwise does nothing.

Responses, errors and limits

A successful request returns a data list and a meta block. aantal (count) is the number of rows in this response, limiet and vanaf are the values we used.

{
  "data": [
    {
      "id": "0b6f1c1e-...",
      "titel": "Zaterdagavond Paradiso",
      "status": "confirmed",
      "soort": "show",
      "start": "2026-10-10T20:00:00+00:00",
      "hele_dag": false,
      "zaal": "Paradiso",
      "stad": "Amsterdam",
      "land": "NL",
      "artiest_id": "5d0c9a52-...",
      "artiest": "Afro Bros",
      "openbaar": true
    }
  ],
  "meta": { "aantal": 1, "limiet": 50, "vanaf": 0 }
}

On an error you get an error block with a fixed code (which you can check against) and a message (readable, in Dutch, and it may change):

{
  "error": {
    "code": "geen_recht",
    "message": "Deze sleutel mag dit onderdeel niet lezen. Zet het vinkje aan bij Instellingen, API-sleutels."
  }
}

Limits

• At most 60 requests per full key per minute. A website key may make 3000 per minute, because all your visitors share it.
• At most 120 requests per IP address per minute, across all keys together.
• Go over that and you get status 429 with the Retry-After header (in seconds). Wait that long and try again.
• Responses from openbare-shows may be cached for a minute (with ?sleutel= in the address also by our network), so a new show, or a website key you pause, can take a minute to come through. All other sources are never cached and a paused full key stops immediately.

Examples

Fetching October's shows with curl

Full key, 50 shows at a time, from the first.

curl -H "Authorization: Bearer ub_live_YOUR_KEY" \
  "https://ultimate-bookings.com/api/v1/shows?van=2026-10-01&tot=2026-10-31&limiet=50&vanaf=0"

Upcoming shows on your website

With a website key. This fills a list on your page and inserts the data as text, not as HTML, so odd characters in a venue name cannot break anything. Want to try it first:

curl "https://ultimate-bookings.com/api/v1/openbare-shows?limiet=10&sleutel=ub_web_YOUR_KEY"

<ul id="ub-shows"></ul>
<script>
  var KEY = "ub_web_YOUR_KEY";
  var ENDPOINT = "https://ultimate-bookings.com/api/v1/openbare-shows?limiet=10&sleutel=" + KEY;
  var list = document.getElementById("ub-shows");

  fetch(ENDPOINT)
    .then(function (response) {
      if (!response.ok) throw new Error("HTTP " + response.status);
      return response.json();
    })
    .then(function (result) {
      if (result.data.length === 0) {
        list.textContent = "No shows announced yet.";
        return;
      }
      result.data.forEach(function (show) {
        // datum is a plain day (YYYY-MM-DD); read it in UTC so it never shifts by a day.
        var date = new Date(show.datum + "T12:00:00Z").toLocaleDateString("en-GB", {
          day: "numeric", month: "long", year: "numeric", timeZone: "UTC"
        });
        var place = [show.zaal, show.stad].filter(Boolean).join(", ");
        var item = document.createElement("li");
        item.textContent = date + ": " + place + (show.artiest ? " (" + show.artiest + ")" : "");
        list.appendChild(item);
      });
    })
    .catch(function () {
      list.textContent = "The list of shows could not be loaded.";
    });
</script>

Fetching everything with pagination

Request one page at a time and increase vanaf by limiet, until a response has fewer rows than the limit. The order is fixed (by start time and then id), so a page never comes back twice or gets skipped as long as nothing changes while you fetch. This works for shows, agenda, contacten and facturen (invoices).

// Node 18 or newer. Fetches all shows, 500 at a time.
const KEY = process.env.UB_KEY; // ub_live_...
const LIMIT = 500;

async function fetchAllShows() {
  const all = [];
  let offset = 0;

  while (true) {
    const url = "https://ultimate-bookings.com/api/v1/shows?limiet=" + LIMIT + "&vanaf=" + offset;
    const response = await fetch(url, { headers: { Authorization: "Bearer " + KEY } });

    if (response.status === 429) {
      const wait = Number(response.headers.get("Retry-After")) || 60;
      await new Promise((done) => setTimeout(done, wait * 1000));
      continue; // the same page once more
    }
    if (!response.ok) {
      const { error } = await response.json();
      throw new Error(error.code + ": " + error.message);
    }

    const { data, meta } = await response.json();
    all.push(...data);
    if (meta.aantal < LIMIT) return all; // last page
    offset += LIMIT;
  }
}

What it can't do (yet)

• Nothing can be written, changed or deleted: the API is read only.
• No files: no contracts, PDFs, riders or attachments.
• No shared shows from other organisations. You only see what belongs to your organisation.