Partner API — Snel aan de slag

Je eerste koppeling past op één scherm.

Probeer het nu — geen sleutel, geen aanmelding

Open dit adres in je browser. Je ziet meteen voorbeeldevenementen.

https://timtim.live/api/partner-network/demo?city=Washington

1
Krijg een testsleutel
Log in, vertel ons wie je bent en druk op Testsleutel maken. Hij begint met tt_test_ en ziet alleen voorbeeldevenementen.

Zoek evenementen

Vraag de evenementen in een stad op.

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

3
Toon het evenement
Elk evenement heeft een naam, datum, plek, afbeelding, prijs en kant-en-klare teksten voor je kaart.
4
Gebruik de buy_url
Gebruik de buy_url die we je geven. Dat is alles. TimTim.Live regelt de toeschrijving in die link.
5
Bekijk de resultaten
Zie gestuurde mensen, verkochte tickets en verdiensten op je dashboard, of vraag ze op.
GET https://api.timtim.live/v1/earnings

Mijn testsleutel krijgen Probeer het zonder sleutel

Status van TimTim.Live

Naslag

Waar je verzoeken naartoe stuurt

https://api.timtim.live/v1

Je verbindingssleutel

Stuur je sleutel mee in de Authorization-header. Testsleutels (tt_test_) zien alleen voorbeeldevenementen. Websitesleutels (tt_pk_live_) mogen in een webpagina staan en lezen alleen evenementen. Serversleutels (tt_sk_live_) blijven op je server en kunnen ook verdiensten lezen. We tonen een sleutel maar één keer — bewaar hem goed.

curl

curl "https://api.timtim.live/v1/events?city=Washington&category=music" \
  -H "Authorization: Bearer tt_test_YOUR_KEY"

JavaScript

const res = await fetch("https://api.timtim.live/v1/events?city=Washington&category=music", {
  headers: { Authorization: "Bearer tt_test_YOUR_KEY" },
});
const { events, next } = await res.json();
for (const event of events) {
  console.log(event.name, event.display.date_label, event.tickets.buy_url);
}

Node

// Node 18+ — keep server keys (tt_sk_live_) on the server
const res = await fetch("https://api.timtim.live/v1/events?city=Washington", {
  headers: { Authorization: `Bearer ${process.env.TIMTIM_KEY}` },
});
if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${problem.title} (${problem.request_id})`);
}
const { events } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.timtim.live/v1/events",
    params={"city": "Washington", "category": "music"},
    headers={"Authorization": f"Bearer {os.environ['TIMTIM_KEY']}"},
)
res.raise_for_status()
for event in res.json()["events"]:
    print(event["name"], event["tickets"]["buy_url"])

PHP

<?php
$ch = curl_init("https://api.timtim.live/v1/events?city=Washington&category=music");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("TIMTIM_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
foreach ($data["events"] as $event) {
  echo $event["name"] . " " . $event["tickets"]["buy_url"] . PHP_EOL;
}

Filters

city: Evenementen in deze stad.
country: Landcode van twee letters, bijvoorbeeld US.
category: Bijvoorbeeld muziek, festival of congres.
from: Evenementen op of na deze datum (2026-10-20).
to: Evenementen op of voor deze datum.
changed_since: Alleen evenementen die na dit moment zijn veranderd.
commissioned: true = alleen evenementen die een beloning geven.
minimum_earnings: Alleen evenementen die minstens zoveel per ticket opleveren.
near: Een plek, bijvoorbeeld near=Paris,FR.
limit: Hoeveel evenementen per pagina, 1 tot 100 (20 als je niets invult).

Vertel me alleen wat er veranderd is

Bewaar de tijd van je laatste synchronisatie en stuur die mee als changed_since. Je krijgt alleen evenementen die veranderd zijn — ook afgelaste en uitverkochte shows. Geen webhook nodig. Evenementen die je niet meer mag tonen, staan in de lijst withdrawn.

GET https://api.timtim.live/v1/events?changed_since=2026-10-06T10:00:00Z

Meer dan één pagina

Als het antwoord next bevat, stuur het terug als cursor= om de volgende pagina te krijgen. Is next leeg, dan heb je alles.

GET https://api.timtim.live/v1/events?city=Paris&cursor=eyJtIjoiZCIs…

Verdienen

Elk evenement heeft earn. Is earn.eligible false, dan heeft het evenement geen beloning — het is toch de moeite waard om te laten zien. Is het true, dan zegt earn.description wat je krijgt, bijvoorbeeld "$5 per geldig ticket". Wordt de aankoop terugbetaald, dan wordt de beloning teruggedraaid.

Bulkfeeds (alles in één bestand)

Sla een bulkfeed op in je dashboard en download dan al zijn evenementen in één gecomprimeerd bestand: GET /v1/bulk/FEED_ID.ndjson.gz of .csv.gz, met je serversleutel. Voeg ?changed_since= toe voor alleen wat veranderd is, ook weggehaalde evenementen. Testsleutels kunnen het nu al proberen; echt gebruik vraagt een controle door TimTim.Live.

GET https://api.timtim.live/v1/bulk/bfs_YOURFEED.ndjson.gz?changed_since=2026-10-06T00:00:00Z

Verkoop tickets in je eigen app (ingebouwde verkoop)

Grote partners kunnen kopers in hun eigen app houden. Vraag GET /v1/events/EVENT_ID/tickets op om te zien wat te koop is, en stuur dan POST /v1/orders met de keuze van de koper. Je krijgt een TimTim.Live-betaallink om voor de koper te openen; de verkoop wordt direct aan je bedrijf toegekend. Testsleutels kunnen het nu al proberen. Echt gebruik vraagt een controle door TimTim.Live en ingeschakelde kaartbetalingen.

POST https://api.timtim.live/v1/orders  (Idempotency-Key: …)  {"event_id": "evt_test_washington_konpa", "ticket_type_id": "tt_test_washington_konpa", "quantity": 2, "buyer_email": "…", "buyer_name": "…"}

Kaartgekoppelde aanbiedingen (banken en beloningsprogramma's)

GET /v1/offers geeft elk evenement dat een beloning betaalt als aanbieding: de organisator, de data waarop je kunt kopen, de prijs, de plek en de beloning. Je klant activeert het via je gevolgde link, en de beloning wordt via /v1/earnings aan je bedrijf betaald. Testsleutels zien voorbeeldaanbiedingen. Echte aanbiedingen hebben een controle door TimTim.Live nodig. Kaartbetalingen direct koppelen vraagt een afspraak met een kaartnetwerk of bank, en is niet aangesloten.

GET https://api.timtim.live/v1/offers?country=US

Status van het evenement en tickets

status is scheduled, postponed, rescheduled, cancelled, sold_out of completed. tickets.availability is available, limited, sold_out, not_on_sale of ended. Als een evenement is afgelast, haal het dan weg.

GET https://api.timtim.live/v1/events/evt_test_washington_konpa

Hoe snel je mag vragen

Testsleutels: 60 verzoeken per minuut. Live-sleutels: 120 per minuut. Ga je sneller, dan krijg je een 429-antwoord met Retry-After, het aantal seconden dat je moet wachten.

Welke evenementen je krijgt

Evenementen die organisatoren op TimTim.Live maken en willen delen. Evenementen die we van andere ticketsites hebben overgenomen, zitten er nooit bij, omdat we niet het recht hebben om ze te delen.

Wat we nooit versturen

Namen van kopers, e-mailadressen, huisadressen, telefoonnummers en kaartgegevens. De Partner API deelt informatie over evenementen, niet over onze leden.

Websitewidget

Eén regel HTML laat evenementen zien op elke website. Gebruik een websitesleutel (tt_pk_live_) en zet je website op de lijst met toegestane websites van de sleutel. Zonder sleutel laat hij voorbeeldevenementen zien.

<script src="https://timtim.live/widget/events.js"
        data-key="tt_pk_live_YOUR_WEBSITE_KEY"
        data-city="Washington" data-category="music" async></script>

Opties: data-city, data-country, data-category, data-limit (1–24), data-earn="true", data-lang en data-color.

OAuth 2.0 (grote koppelingen)

Optioneel. Maak een OAuth-client op je dashboard. Ruil daarna de client-ID en het geheim in voor een toegangstoken van een uur, en stuur dat token in plaats van een sleutel. Het geheim gaat nooit mee met je API-verzoeken, en je kunt om minder rechten (scopes) vragen dan de client heeft.

# 1. Trade the client ID and secret for a one-hour token
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=events:read events:details" \
  https://api.timtim.live/v1/oauth/token
# → {"access_token":"tt_at_…","token_type":"Bearer","expires_in":3600,"scope":"events:read events:details"}

# 2. Use the token exactly like a key
curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.timtim.live/v1/events?city=Washington"

Wil je een token eerder stoppen? Stuur het met POST naar /v1/oauth/revoke, met dezelfde client-ID en hetzelfde geheim. Zet je de client uit op je dashboard, dan stoppen al zijn tokens tegelijk.

Vergrendel een sleutel op je servers

Optioneel. Open op je dashboard "Vergrendel op mijn servers" onder een serversleutel, testsleutel of OAuth-client en vul de openbare adressen van je servers in. Oproepen — en tokenaanvragen — van ergens anders worden geweigerd met ip_not_allowed, zelfs met de juiste sleutel.

Clientcertificaten (mTLS): koppel je TLS-clientcertificaat aan een sleutel en roep daarna https://api.timtim.live ermee aan. Elke oproep moet dat certificaat laten zien; de TLS-handshake bewijst dat jij de privésleutel ervan hebt.

# Your certificate's SHA-256 — paste this (or the PEM) under "Lock to my servers"
openssl x509 -in client.crt -noout -fingerprint -sha256

# Every call then presents the certificate
curl --cert client.crt --key client.key \
  -H "Authorization: Bearer $KEY" "https://api.timtim.live/v1/events?city=Washington"

WordPress-plugin

Gebruik je WordPress? Installeer TimTim.Live Events: een blok en een shortcode die evenementen laten zien met je eigen TimTim.Live-ticketlinks. Hij is gemaakt door TimTim.Live, praat alleen met timtim.live en werkt alleen bij vanaf timtim.live.

Upload het bestand via Plugins → Nieuwe toevoegen → Plugin uploaden. Plak je websitesleutel in Instellingen → TimTim.Live Events en klik op Test Connection. Voeg daarna het blok TimTim.Live Events toe aan een pagina.

Download de WordPress-plugin

[timtim_events city="Washington" category="music" limit="6"]

Feeds

Dezelfde evenementen als JSON Feed, RSS, XML, CSV of een agenda (.ics) waarop Google Calendar, Apple Calendar en Outlook zich kunnen abonneren. Feedlezers kunnen geen headers sturen, dus zet een websitesleutel of een testsleutel in ?key=. Zet nooit een serversleutel in een link.

https://timtim.live/v1/feeds/events.json?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.rss?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.xml?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.csv?key=tt_pk_live_YOUR_KEY&city=Paris
https://timtim.live/v1/feeds/events.ics?key=tt_pk_live_YOUR_KEY&city=Paris

Webhooks

Voeg een adres toe op je dashboard en we sturen er een bericht naartoe als er iets verandert: event.changed of earnings.changed. Webhooks zijn niet verplicht — changed_since geeft je dezelfde informatie.

{
  "id": "whd_8Fk2mQxR7tLp",
  "type": "event.changed",
  "created_at": "2026-10-06T15:04:05.000Z",
  "mode": "live",
  "data": {
    "event": {
      "id": "ev_…",
      "name": "…",
      "status": "cancelled",
      "tickets": {
        "availability": "ended",
        "buy_url": "https://timtim.live/b/…"
      },
      "…": "the same event object as GET /v1/events"
    }
  }
}

Controleer elk bericht: het is ondertekend met jouw geheim. Weiger alles wat ouder is dan vijf minuten, en negeer een TimTim-Delivery-Id die je al hebt verwerkt.

// Node — Express with the RAW body (do not JSON.parse before checking)
import crypto from "node:crypto";

app.post("/timtim", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("TimTim-Signature") ?? "";           // t=1700000000,v1=<hex>
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const body = req.body.toString("utf8");
  const expected = crypto.createHmac("sha256", process.env.TIMTIM_WEBHOOK_SECRET)
    .update(`${parts.t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const same = expected.length === (parts.v1 ?? "").length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!fresh || !same) return res.sendStatus(400);

  const message = JSON.parse(body);                            // { id, type, mode, data }
  if (alreadyHandled(req.get("TimTim-Delivery-Id"))) return res.sendStatus(200);
  // message.type === "event.changed"    → message.data.event
  // message.type === "earnings.changed" → message.data.earning
  res.sendStatus(200);
});

Antwoord binnen 10 seconden met een 2xx. Zo niet, dan proberen we het opnieuw na 1 minuut, 5 minuten, 30 minuten, daarna na 2, 6, 12 en 24 uur, en dan stoppen we. We volgen nooit doorverwijzingen.

De sandbox

Testsleutels krijgen voorbeeldevenementen met het label TESTEVENEMENT — GEEN ECHT GELD. Open een buy_url, druk op Testticket kopen en vraag daarna je verdiensten op. Doe een terugbetaling na en zie hoe die wordt teruggedraaid.

Als er iets misgaat

Fouten leggen zichzelf uit in gewone woorden, met een titel en wat je daarna moet doen. Elk antwoord heeft een TimTim-Request-Id. Stuur die naar ons, dan vinden we je verzoek.

401missing_keyPlease add your TimTim.Live key. Send it as: Authorization: Bearer tt_test_… — get a test key at /partners/dashboard.
401invalid_keyWe do not recognise that key. Check you copied the whole key, or make a new one at /partners/dashboard.
401revoked_keyThat key was switched off. Make a new key at /partners/dashboard.
403partner_inactiveThis partner account cannot use live keys right now. Your test key still works. Contact TimTim.Live partnerships to review the account.
403missing_scopeThis key is not allowed to do that. Earnings need a secret key (tt_sk_live_…) or a test key, used from your server.
403domain_not_allowedThis website is not allowed to use this key. Add the website to the key's allowed domains at /partners/dashboard.
400unknown_parameterWe do not know one of those parameters. See /partners/docs for the list.
400invalid_countryWe could not read that country. Use a two-letter code, for example country=US or country=FR.
400invalid_dateWe could not read that date. Dates look like 2026-10-20.
400invalid_changed_sinceWe could not read changed_since. Use a full time, for example changed_since=2026-10-06T10:00:00Z.
400invalid_booleanThat value must be true or false. For example commissioned=true.
400invalid_numberThat value must be a number. For example minimum_earnings=5.
400invalid_nearWe could not find that place. Try near=Paris,FR or city=Paris&country=FR.
400invalid_locationWe could not read that location. Send lat, lng and optionally radius in kilometres.
400invalid_limitlimit must be between 1 and 100. Leave it out to get 20.
400invalid_cursorThat cursor is not one we gave you. Use the `next` value from the previous page exactly as it came.
404event_not_foundWe could not find that event. It may have been removed, or it is not shared with partners.
403capability_requiredCard-linked offers are not switched on for your account. Offers are an enterprise feature. Your test key shows sample offers now; ask TimTim.Live partnerships to review your account for live offers.
403server_key_requiredThis is for your server only. Use a secret key (tt_sk_live_…) or a test key from your server, never a website key in a web page.
403commerce_not_enabledSelling tickets in your own app is not switched on for your account. This is an enterprise feature (EMBEDDED_CHECKOUT). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, use each event's buy_url.
503checkout_not_openCard payments are not open on TimTim.Live yet. Send the buyer to the event's buy_url instead. Your test key can still rehearse orders.
409ticket_not_availableThat ticket cannot be bought right now. It may be sold out, not on sale yet, or no longer on sale. Ask /v1/events/{id}/tickets for what is on sale now.
400order_invalidWe could not read that order. See /partners/docs for the fields an order needs.
400idempotency_key_requiredPlease send an Idempotency-Key header. 8 to 80 letters, digits, - or _. Send the same key again to retry safely — you will get the same order, never a second one.
404order_not_foundWe could not find that order. Only orders your company began with this kind of key (test or live) can be read here.
403bulk_not_enabledBulk feeds are not switched on for your account. This is an enterprise feature (BULK_FEEDS). Your test key can try it now; ask TimTim.Live partnerships to review your account. Until then, page through /v1/events or the feeds.
404bulk_not_foundWe could not find that bulk feed. Use the address shown on /partners/dashboard: /v1/bulk/<subscription id>.ndjson.gz or .csv.gz.
429bulk_too_soonA full file was made for this feed a few minutes ago. Full files can be made every 15 minutes. For what changed since, add changed_since=<time> — that is not limited.
410event_withdrawnThis event is no longer shared with partners. Stop showing it and remove its buy_url. Nothing else is needed — your old link still takes people to the event page.
400invalid_trackWe could not read that tracking signal. Send {"type":"impression"}, {"type":"event_view","event_id":"…"} or {"type":"event_click","event_id":"…"}. Sales are recorded by TimTim.Live, never sent from a page.
404not_foundThere is nothing at this address. The Partner API lives at /v1/events, /v1/events/{id}, /v1/offers and /v1/earnings.
405method_not_allowedThis address does not answer that method. The Allow header lists the methods it answers.
401key_in_urlSend your key in the Authorization header. Only /v1/feeds reads a key from the URL (?key=). Everywhere else use Authorization: Bearer <key> — keys in URLs end up in logs.
403ip_not_allowedThis key only works from your listed servers. Call from an address on the key's allowlist, or change the list at /partners/dashboard.
401certificate_requiredThis key needs your client certificate. Connect to https://api.timtim.live with the TLS client certificate pinned to this key.
401certificate_mismatchThat is not the certificate pinned to this key. Use the certificate whose SHA-256 is on your dashboard, or pin the new one there.
429rate_limitedToo many requests — please slow down. Wait the number of seconds in Retry-After, then try again.
503unavailableThe Partner API is resting for a moment. Please try again in a minute.
500server_errorSomething went wrong on our side. Please try again. If it keeps happening, send us your TimTim Request ID.

Het contract

De volledige beschrijving van elk veld, in het OpenAPI-formaat dat je tools kunnen lezen.

openapi.yaml downloaden

Hoe live sleutels opengaan

Je testsleutel werkt meteen. Voor live sleutels kijkt een persoon bij TimTim.Live naar je bedrijfsnaam, je website en hoe je evenementen gaat tonen. Je ziet het antwoord op je dashboard.

Nieuws over de TimTim.Live API

Versie 1 wordt alleen maar groter. We voegen nieuwe dingen toe. We halen niets weg en geven niets wat er al is een andere naam.

2026-10-08 — Antwoorden over evenementen hebben nu een ETag. Stuur die terug in If-None-Match en krijg een snelle 304 als er niets veranderd is. Optioneel.
2026-10-08 — Websitesleutels tellen nu elke bezoeker apart, zodat drukke sites blijven werken. Geen actie nodig.
2026-10-07 — Clientcertificaten (mTLS) zijn open: koppel je certificaat aan een sleutel op je dashboard. Optioneel. Geen actie nodig.
2026-10-07 — Bulkfeeds: elk evenement dat je mag tonen, in één bestand, op GET /v1/bulk. Optioneel. Geen actie nodig.
2026-10-07 — De API heeft een eigen adres: https://api.timtim.live/v1. https://timtim.live/v1 blijft werken. Geen actie nodig.
2026-10-06 — Je eigen betaalpagina met jouw merk op timtim.live/checkout. Optioneel. Geen actie nodig.
2026-10-06 — Verkoop tickets in je eigen app: GET /v1/events/EVENT_ID/tickets en POST /v1/orders. Optioneel. Geen actie nodig.
2026-10-06 — Een openbare statuspagina op /partners/status, elke minuut gecontroleerd. Geen actie nodig.
2026-10-06 — Maandoverzichten voor bedrijven: GET /v1/settlements. Geen actie nodig.
2026-10-06 — Postbacks: zet ?sub_id= in een kooplink en we sturen het met de verkoop naar je terug. Optioneel. Geen actie nodig.
2026-10-06 — Kaartgekoppelde aanbiedingen voor banken en beloningsprogramma's: GET /v1/offers. Optioneel. Geen actie nodig.
2026-10-06 — Agendafeed: /v1/feeds/events.ics voor Google Calendar, Apple Calendar en Outlook. Je hoeft niets te doen.
2026-10-06 — Vergrendel een sleutel op je servers: lijsten met toegestane IP's nu, clientcertificaten (mTLS) op api.timtim.live. Optioneel. Je hoeft niets te doen.
2026-10-06 — OAuth 2.0 client credentials voor grote koppelingen: POST /v1/oauth/token en /v1/oauth/revoke. Sleutels blijven werken. Je hoeft niets te doen.
2026-10-06 — WordPress-plugin 1.0.0: een blok, een shortcode en een instellingenpagina. Hij werkt zichzelf bij vanaf timtim.live. Je hoeft niets te doen.
2026-10-06 — Websitewidget, JSON/RSS/XML/CSV-feeds en webhooks (event.changed, earnings.changed). Je hoeft niets te doen.
2026-10-06 — Partner API v1: evenementen, één evenement, verdiensten en de sandbox. Je hoeft niets te doen.