Partner API — Schnellstart

Ihre erste Integration passt auf einen Bildschirm.

Jetzt ausprobieren – ohne Schlüssel, ohne Anmeldung

Öffnen Sie diese Adresse in Ihrem Browser. Sie sehen sofort Beispiel-Events.

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

1
Testschlüssel holen
Melden Sie sich an, sagen Sie uns, wer Sie sind, und klicken Sie auf Testschlüssel erstellen. Er beginnt mit tt_test_ und sieht nur Beispiel-Events.

Events finden

Fragen Sie nach Events in einer Stadt.

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

3
Event anzeigen
Jedes Event hat Name, Datum, Ort, Bild, Preis und fertige Texte für Ihre Karte.
4
Die buy_url nutzen
Nutzen Sie die buy_url, die wir Ihnen geben. Das ist alles. TimTim.Live regelt die Zuordnung in diesem Link.
5
Ergebnisse ansehen
Sehen Sie geschickte Personen, verkaufte Tickets und Einnahmen in Ihrem Dashboard – oder fragen Sie sie ab.
GET https://api.timtim.live/v1/earnings

Meinen Testschlüssel holen Ohne Schlüssel ausprobieren

TimTim.Live Status

Referenz

Wohin Sie Anfragen senden

https://api.timtim.live/v1

Ihr Verbindungsschlüssel

Senden Sie Ihren Schlüssel im Authorization-Header. Testschlüssel (tt_test_) sehen nur Beispiel-Events. Website-Schlüssel (tt_pk_live_) dürfen in einer Webseite stehen und lesen nur Events. Server-Schlüssel (tt_sk_live_) bleiben auf Ihrem Server und können auch Einnahmen lesen. Wir zeigen jeden Schlüssel nur einmal — bewahren Sie ihn sicher auf.

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;
}

Filter

city: Events in dieser Stadt.
country: Ländercode mit zwei Buchstaben, zum Beispiel US.
category: Zum Beispiel Musik, Festival oder Konferenz.
from: Events an oder nach diesem Datum (2026-10-20).
to: Events an oder vor diesem Datum.
changed_since: Nur Events, die sich nach diesem Zeitpunkt geändert haben.
commissioned: true = nur Events, die eine Prämie zahlen.
minimum_earnings: Nur Events, die mindestens so viel pro Ticket zahlen.
near: Ein Ort, zum Beispiel near=Paris,FR.
limit: Wie viele Events pro Seite, 1 bis 100 (20, wenn Sie nichts angeben).

Nur sagen, was sich geändert hat

Speichern Sie die Zeit Ihres letzten Abgleichs und senden Sie sie als changed_since. Sie bekommen nur Events, die sich geändert haben — auch Absagen und ausverkaufte Shows. Kein Webhook nötig. Veranstaltungen, die du nicht mehr zeigen darfst, kommen in der Liste withdrawn.

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

Mehr als eine Seite

Wenn die Antwort next enthält, senden Sie es als cursor= zurück, um die nächste Seite zu bekommen. Wenn next leer ist, haben Sie alles.

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

Verdienen

Jedes Event hat earn. Ist earn.eligible false, hat das Event keine Prämie — es lohnt sich trotzdem, es zu zeigen. Ist es true, sagt earn.description, was Sie bekommen, zum Beispiel „$5 pro berechtigtem Ticket“. Wird der Kauf erstattet, wird die Prämie zurückgebucht.

Bulk-Feeds (alles in einer Datei)

Speichern Sie einen Bulk-Feed in Ihrem Dashboard und laden Sie dann alle seine Events in einer komprimierten Datei herunter: GET /v1/bulk/FEED_ID.ndjson.gz oder .csv.gz, mit Ihrem Server-Schlüssel. Fügen Sie ?changed_since= hinzu, um nur Änderungen zu erhalten, auch entfernte Events. Testschlüssel können es jetzt ausprobieren; echter Einsatz braucht eine Prüfung durch TimTim.Live.

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

Tickets in Ihrer eigenen App verkaufen (eingebetteter Handel)

Große Partner können Käufer in ihrer eigenen App halten. Fragen Sie mit GET /v1/events/EVENT_ID/tickets, was im Verkauf ist, und senden Sie dann POST /v1/orders mit der Wahl des Käufers. Sie erhalten einen TimTim.Live-Zahlungslink, den Sie für den Käufer öffnen; der Verkauf wird direkt Ihrem Unternehmen gutgeschrieben. Testschlüssel können es jetzt ausprobieren. Echter Einsatz braucht eine Prüfung durch TimTim.Live und eingeschaltete Kartenzahlungen.

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": "…"}

Kartengebundene Angebote (Banken und Prämienprogramme)

GET /v1/offers liefert jedes Event, das eine Prämie zahlt, als Angebot: den Veranstalter, die Tage, an denen man kaufen kann, den Preis, den Ort und die Prämie. Ihr Kunde aktiviert es über Ihren verfolgten Link, und die Prämie wird über /v1/earnings an Ihr Unternehmen gezahlt. Testschlüssel sehen Beispielangebote. Echte Angebote brauchen eine Prüfung durch TimTim.Live. Kartenzahlungen direkt zuzuordnen braucht eine Vereinbarung mit einem Kartennetzwerk oder einer Bank und ist nicht angebunden.

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

Event-Status und Tickets

status ist scheduled, postponed, rescheduled, cancelled, sold_out oder completed. tickets.availability ist available, limited, sold_out, not_on_sale oder ended. Wenn ein Event abgesagt wird, nehmen Sie es offline.

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

Wie schnell Sie fragen dürfen

Testschlüssel: 60 Anfragen pro Minute. Live-Schlüssel: 120 pro Minute. Wer schneller fragt, bekommt eine 429-Antwort mit Retry-After, der Zahl der Sekunden zum Warten.

Welche Events Sie bekommen

Events, die Veranstalter auf TimTim.Live erstellen und teilen wollen. Events, die wir von anderen Ticket-Seiten übernommen haben, sind nie dabei, weil wir nicht das Recht haben, sie zu teilen.

Was wir nie senden

Namen von Käufern, E-Mail-Adressen, Wohnadressen, Telefonnummern und Kartendaten. Die Partner API teilt Infos über Events, nicht über unsere Mitglieder.

Website-Widget

Eine Zeile HTML zeigt Events auf jeder Website. Nutzen Sie einen Website-Schlüssel (tt_pk_live_) und tragen Sie Ihre Website in die Liste der erlaubten Websites des Schlüssels ein. Ohne Schlüssel zeigt es Beispiel-Events.

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

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

OAuth 2.0 (große Integrationen)

Optional. Erstellen Sie in Ihrem Dashboard einen OAuth-Client. Tauschen Sie dann seine Client-ID und sein Secret gegen ein Zugriffstoken, das eine Stunde gilt, und senden Sie dieses Token statt eines Schlüssels. Das Secret reist nie mit Ihren API-Anfragen mit, und Sie können weniger Rechte (Scopes) anfordern, als der Client hat.

# 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"

Um ein Token früher zu beenden, senden Sie es per POST an /v1/oauth/revoke, mit derselben Client-ID und demselben Secret. Schalten Sie den Client in Ihrem Dashboard aus, enden alle seine Tokens auf einmal.

Einen Schlüssel auf Ihre Server sperren

Optional. Öffnen Sie in Ihrem Dashboard „Auf meine Server sperren“ unter einem Server-Schlüssel, Testschlüssel oder OAuth-Client und tragen Sie die öffentlichen Adressen Ihrer Server ein. Aufrufe — und Token-Anfragen — von überall sonst werden mit ip_not_allowed abgelehnt, selbst mit dem richtigen Schlüssel.

Client-Zertifikate (mTLS): Verknüpfen Sie Ihr TLS-Client-Zertifikat mit einem Schlüssel und rufen Sie dann https://api.timtim.live damit auf. Jeder Aufruf muss dieses Zertifikat zeigen; der TLS-Handshake beweist, dass Sie seinen privaten Schlüssel haben.

# 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

Sie nutzen WordPress? Installieren Sie TimTim.Live Events: ein Block und ein Shortcode, die Events mit Ihren eigenen TimTim.Live-Ticketlinks zeigen. Es kommt von TimTim.Live, spricht nur mit timtim.live und wird nur über timtim.live aktualisiert.

Laden Sie die Datei unter Plugins → Installieren → Plugin hochladen hoch. Fügen Sie Ihren Website-Schlüssel unter Einstellungen → TimTim.Live Events ein und klicken Sie auf Test Connection. Fügen Sie dann den Block TimTim.Live Events zu einer beliebigen Seite hinzu.

WordPress-Plugin herunterladen

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

Feeds

Dieselben Events als JSON Feed, RSS, XML, CSV oder als Kalender (.ics), den Google Calendar, Apple Calendar und Outlook abonnieren können. Feed-Reader können keine Header senden. Setzen Sie deshalb einen Website-Schlüssel oder einen Testschlüssel in ?key=. Setzen Sie nie einen Server-Schlüssel in einen 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

Tragen Sie in Ihrem Dashboard eine Adresse ein. Wir schicken ihr eine Nachricht, wenn sich etwas ändert: event.changed oder earnings.changed. Webhooks sind freiwillig — changed_since gibt Ihnen dieselben Informationen.

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

Prüfen Sie jede Nachricht: Sie ist mit Ihrem Geheimnis signiert. Lehnen Sie alles ab, was älter als fünf Minuten ist, und ignorieren Sie eine TimTim-Delivery-Id, die Sie schon bearbeitet haben.

// 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);
});

Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx. Sonst versuchen wir es erneut nach 1 Minute, 5 Minuten, 30 Minuten, dann nach 2, 6, 12 und 24 Stunden, und hören dann auf. Wir folgen nie Weiterleitungen.

Die Sandbox

Testschlüssel bekommen Beispiel-Events mit der Markierung TEST-EVENT — KEIN ECHTES GELD. Öffnen Sie eine buy_url, klicken Sie auf Testticket kaufen und fragen Sie dann Ihre Einnahmen ab. Simulieren Sie eine Erstattung und sehen Sie, wie sie zurückgebucht wird.

Wenn etwas schiefgeht

Fehler erklären sich in einfachen Worten, mit einem Titel und dem nächsten Schritt. Jede Antwort hat eine TimTim-Request-Id. Schicken Sie sie uns, dann finden wir Ihre Anfrage.

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.

Der Vertrag

Die vollständige Beschreibung jedes Feldes im OpenAPI-Format, das Ihre Tools lesen können.

openapi.yaml herunterladen

So öffnen sich Live-Schlüssel

Ihr Testschlüssel funktioniert sofort. Bei Live-Schlüsseln schaut sich ein Mensch bei TimTim.Live Ihren Firmennamen, Ihre Website und die Art an, wie Sie Events zeigen werden. Die Antwort sehen Sie in Ihrem Dashboard.

Neues zur TimTim.Live API

Version 1 wird nur größer. Wir fügen Neues hinzu. Was schon da ist, entfernen wir nicht und benennen es nicht um.

2026-10-08 — Antworten zu Events tragen jetzt ein ETag. Senden Sie es als If-None-Match zurück und erhalten Sie ein schnelles 304, wenn sich nichts geändert hat. Optional.
2026-10-08 — Website-Schlüssel zählen jetzt jeden Besucher einzeln, damit stark besuchte Seiten weiter funktionieren. Sie müssen nichts tun.
2026-10-07 — Client-Zertifikate (mTLS) sind offen: Binden Sie Ihr Zertifikat in Ihrem Dashboard an einen Schlüssel. Optional. Sie müssen nichts tun.
2026-10-07 — Bulk-Feeds: jedes Event, das Sie zeigen dürfen, in einer Datei, unter GET /v1/bulk. Optional. Sie müssen nichts tun.
2026-10-07 — Die API hat eine eigene Adresse: https://api.timtim.live/v1. https://timtim.live/v1 funktioniert weiter. Nichts zu tun.
2026-10-06 — Ihre eigene Bezahlseite mit Ihrer Marke unter timtim.live/checkout. Optional. Sie müssen nichts tun.
2026-10-06 — Tickets in Ihrer eigenen App verkaufen: GET /v1/events/EVENT_ID/tickets und POST /v1/orders. Optional. Sie müssen nichts tun.
2026-10-06 — Eine öffentliche Statusseite unter /partners/status, jede Minute geprüft. Sie müssen nichts tun.
2026-10-06 — Monatliche Abrechnungen für Unternehmen: GET /v1/settlements. Sie müssen nichts tun.
2026-10-06 — Postbacks: Hängen Sie ?sub_id= an einen Kauf-Link, und wir schicken es Ihnen mit dem Verkauf zurück. Optional. Sie müssen nichts tun.
2026-10-06 — Kartengebundene Angebote für Banken und Prämienprogramme: GET /v1/offers. Optional. Sie müssen nichts tun.
2026-10-06 — Kalender-Feed: /v1/feeds/events.ics für Google Calendar, Apple Calendar und Outlook. Sie müssen nichts tun.
2026-10-06 — Einen Schlüssel auf Ihre Server sperren: IP-Freigabelisten jetzt, Client-Zertifikate (mTLS) auf api.timtim.live. Optional. Sie müssen nichts tun.
2026-10-06 — OAuth 2.0 Client Credentials für große Integrationen: POST /v1/oauth/token und /v1/oauth/revoke. Schlüssel funktionieren weiter. Sie müssen nichts tun.
2026-10-06 — WordPress-Plugin 1.0.0: ein Block, ein Shortcode und eine Einstellungsseite. Es aktualisiert sich selbst über timtim.live. Sie müssen nichts tun.
2026-10-06 — Website-Widget, Feeds als JSON/RSS/XML/CSV und Webhooks (event.changed, earnings.changed). Sie müssen nichts tun.
2026-10-06 — Partner API v1: Events, ein einzelnes Event, Einnahmen und die Sandbox. Sie müssen nichts tun.