Partner- API - Schnell ufänken

Äre éischt Integratioun passt zu ee Bildschierm.

Probéieren elo - kee Schlëssel, keng Arécken

Dëse Adress an Äerem Browser opmaachen. Dir kriss de Beispill- Eventen direkt.

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

1
E Testschlëssel ufroen
Umellen, verzielt eis un ob der dir sidd, an dréckt op den Testschlëssel no. Et fänket mat t_test _an gesinn nëmme Beispiller.

Eventen sichen

Fro fir d'Ereegnisse an enger Stadt.

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

3
Weis d'Evenement
All Évenement mat engem Numm, Datum, Positioun, Bild, Pries an preichéiséiert Beschrëftungen fir är Kaart.
4
Benotz w_urf
Benotz w.e.g. de Ka_user. - Danke, Kinder. TimTim.Live bréiert den Typ vum Link.
5
Resultater uweisen
Fir Leit zesummengesafen, z'Lüsten ob deng Dash beséirten an et Erfänken.
GET https://api.timtim.live/v1/earnings

Mye Test- Schlëssel ufroen ouni ee Schlëssel probéieren

TimTim.Live Status

Differenzen uweisen

Wo soll Ufro verschécken?

https://api.timtim.live/v1

Äre Schlëssel fir d'Verbindung

Äre Schlëssel an der Autoriséierungsheader verschécken. Schlësselen testen (t_test_) gesinn Beispiller. Website-Schlëssel (t_pk_live_) kann op enger Web- Säit sitten an nëmme Liesen טרעפֿענישן. De Serverschlëssel (t_sk_live_) bleiwen op den Server a kann och Erzielen liesen. Mir weisen een Schlëssel een Kéier — kee sëcher.

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

Filteren

city: Eventuert an dëser Stadt.
country: Zwou- Buchstawen Landcode, zum Beispill US.
category: Zum Beispill Musik, Festival oder Konferenz.
from: Eventuelen un oder nach dësem Datum (2026-10-20).
to: Eventen an oder uer dësem Datum.
changed_since: Nëmme déi nach dëser Zäit geännert gin.
commissioned: true = Nëmme Geschiwen, déi e Beloun erausgoen.
minimum_earnings: Nëmme Ewechheeten, deen wéinstens och villen Rechnung unzegoen.
near: Eng Positioun, zum Beispill bei der nächster=Paris,FR.
limit: Wéivill Eventen pro Säit, 1 bis 100 (20 wann s de et ausmaache wëllt).

Verziel me nëmmen wat anescht

D'Zäit vun der leschter Synchronisatioun späicheren an sou dass se als verännert_Sid verschéckt gëtt. Där kënnt nëmmen d'Beendungen, déi geännert gi sinn - einschließlich vun Ofbriechungen an ausgelaften Weis. Kee Webhook gebraucht. Event du muss ophâlden mat der haalen Lëscht un.

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

Méi wéi eng Säit

Wann d'Äntwert nächsten huet, dann weidersichen se zeréck als Curseur= fir de nächsten Säit ze erofzelueden. Wann et de nächsten ass eidel, hues du alles.

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

Ëmfänkt

Eevenement déngscht. Wann e verdient ass (falsch) Wann et waar ass, da gëtt et geschwéi et.Beschreiwung benotzt wat dir kriss, zum Beispill "$5 pro béichbare Ticket". Wann d'Kaf erofgelueden gëtt, gëtt d'Beloun erreechent.

Bulkfeeds ( alles an enger Datei)

Eng groussen Feed an den Dashfeld späicheren. Dann all Event se an enger kompriméierter Datei eroflueden, mat ärem Server-Schlëssel: GET /v1/bulk/FEED_ID.ndjson.gz oder .csv.gz. Dobäisetze?verännert _Sind fir just wat geännert ass, +zéin Évenement dréckt zesummen. Schlësselen kënnen elo probéieren; Live- Benotzung bräucht eng TimTim.Live-Bewertung.

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

Tickets an ärem eigenen App verkaufen (embeddeden Kommerz)

Grousse Partner kënnen Käfer an hirer Eegenen. Fro GET /v1/events/EVENT_ID/tickets fir wat am Verkoop ass, dann mat der Wahl vum Käufer. Dir krus eng TimTim.Live Vertragslink fir den Kafer opzemaachen; de Verkoop gëtt direkt u ärt Beréiwert geschriwwent. Schlësselen kënnen elo probéieren. Live- Benotzt bräuch eng TimTim.Live Bewäertung an eng Kaartebetalinger, deen er virgesat gouf.

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

Kaartef Visitéiert Offerten (Banken a Belohnungsprogrammen)

GET /v1/Additiounen weisen all Évenement d'Belonung als Offatioun aus. All Offatiounen sinn den Organisator un den Datumen, deen der kafir, den Duerch, d'Plais an d'Belonen kaft. Är Client aktiveert et iwwer deng Link, an d'Beloun gëtt zu ärer Firma iwwer /v1/earungen gëlt. Tasten fir Beispiller ze sichen. Live-Distributiounen brauchen eng TimTim.Live Bewäertung. Mat der Kaartebetalinger direkt bräuch eng Afkommend mat enger Netzwierk oder enger Bank, an déi net verbonnen ass.

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

Event Status a Büsten

De Status ass planéiert, verlëzt, zeréckgeluecht, ofgebrach oder fäerdeg.Aktioun ass verfügbar, Limitéiert, Aus_beräich, net_on_sale oder fäerdeg. Wann e Event ofgebrach ass, huelen se erof.

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

Wéi schnell du froen kanns

Test Schlësselen: 60 huet eng Minutt. Live Schlësselen: 120 eng Minutt. Vir méi schnell ufänken, gi et eng 429 Säit mat No méi probéieren, d' Unzuel vu Sekonnen, fir ze woaeren.

Hoffentlech Event dobaimaachen

Events, déi TimTim.Live Organisators erstellen an auswielen, fir ze deelen. Eventen déi mir aus aner Ticket- Säiten ugebuede ginn, ginn ni ugebuer.

Wat mer ni schécken

Käuernummen, E- Mail- Adressen, Adressen, Telefonnummeren a Kaart Detailer. D'Partner- API deelt Event Informatiounen, net eisen Members.

Website- Widget

Eng Zeil vu HTML- Fënsteren op iergend eng Website uweisen. Benotzt en Website- Schlëssel (t_pk_live_) an andeems ärt Website op de Lëscht vun de Schlëssel erlaabt ass. Mat keng Schlëssel enthalen Beispiller.

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

Optiounen: Daten- Stad, Daten- Land, Daten- Kategorie, Donnéen- Limit (1- 24), Daten- Earn=" Wier", Daten- Lang an Daten- Faarwen.

OAuth 2.0 (gréisst Integratiounen)

Optional. Maach e OAuth- Client um d'Dashboard un. Verhandel däin Client ID an Sëcherheets geheim fir e Zougang vu enger Stonn. Dat Zeechen amplaz vun engem Schlëssel verschécken. Den Sëcherheetsrisiko geet ni mat ärem API-Uerdrock, an du krus no manner Scope as de Client huet.

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

Fir eng tokunft zéien unzegoen, pist et un /v1/oauth/rechner mat der selwechter Client ID an Sëcherheetsberäichen. Den Client um ärem Dashpaneel uschalten is all är Zeechen.

E Schlëssel op Äre Server spären

Optional. Am Dashbord fannen ee Schlëssel vum Server, Test- Schlëssel oder OAuth- Client. "Lock op myn Serveren" an Lëscht Äre öffentlechen Adressen vun Äre Servere. Uruffen - an Taken- Anfragen - vun iech méi neien as gëier verlaangen mat ip_ net_ erlaabt, esou mat dem rechten Schlëssel.

Client- Zertifikaten (mTLS), fir grousse Bedriften: Gëff eis ären ID- Kaart (e Zertifikat) an ouni engem Schlëssel op. Urhebt dann https://api.tim.live mat et. Nëmmen Äntwert vum Server, déi dat Zertifikat enthält.

# 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

WordPress benotzen? TimTim.Live Eventen installéieren: ee Block an engem Kuerzcode, deen Däer Ewechheeten mat Ärem egen TimTim.Live Ticket-Links uweisen. Et gëtt vu TimTim.Live, schwätzen just fir tim.live, an Aktualiséierungen just äus der tim. live.

D'Datei mat Pluginen eroflueden → Nei dobäisetzen → Nach eng Kéier eroplueden. Pechen Ären Schlëssel an den Astellungen → TimTim.Live Eventen a klickt op d'Verbinding testen. Gëff den TimTim.Live Event Block op iergend eng Säit un.

Den WordPress Plugin eroflueden

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

Feeds

Déi selwechte Eventen als JSON Feed, RSS, XML, CSV oder eng Kalennerdatei (.ics). Google Kalenner, Apple- Kalenner an Outlook kënnen den Kalenner abonneren. Feed-Leeser kënnen net Headeren schécken, sou en Website-Schlëssel oder engem Test-Schlëssel an ?key=ginn. Ni ee Schlëssel fir den Server an engem Link setzen.

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

WebhooksName

Dobäisetze eng Adress am Dashfeld an mir schécken eng Noriicht wann eppes verännert gëtt: Event.Ännert oder erhaalen. Webhooks sinn optional - verännert _sind d'selwecht Informatioun.

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

Iech all Noriicht sichen: Et ass mat Ärem Sëcherheetsschlëssel geännert ginn. Verweigert näicht méi eeler als 5 Minutten, an ignoréier eng TimTim-Delivery-ID gëtt de schonn duerchgeféiert.

// 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 mat ier 2xx säit 10 Sekonnen. Wann net, probéiert mer nach eng Minutt nach eng Kéier, 5 Minutten, 30 Minutten, dann 2, 6, 12 an 24 Stonnen, dann stoppe. Mir fänke nie mat Ärem Weiterleitungen un.

Den Sandbox

Schlësselen kréien Beispiller, déi am Testen erausgeworf ginn - Kee reell Ferifikaasje. Eng Buy-Uerl opmaachen, dréckt op Test-Bill kafen, dann froen um är Erfolleg. Eng Refundatioun simuléieren an eng rekuckend ophuelen.

Wann eppes geschett ass

Feeler verklart sech am einfachen Wierder, mat engem Titel an an wat zeechnen. All d'Äntwert mat enger TimTim-RequestQAccel Schéck et un eis un duer Ufro.

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.
409idempotency_conflictThat Idempotency-Key was already used for a different order. Send exactly the same order to get the same answer back, or use a new Idempotency-Key for a new order.
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.

Den Auftrag

Déi komplett Beschreiwung vun all Felder. Am "OpenAPI" - Format, déi Äre Hëllefsprogramm liesen kënnen.

Eroflueden

Wéi live Schlësselen opgemat ginn

Äre Test- Schlëssel funktionéiert direkt. Fir Leitzéiche Schlësselen, eng Persoun wou der TimTim.Live seng Numm, Äre Websäiten a wéi dir Eventen uweisen. Dir kriss d'Äntwert um deng Dashbord.

TimTim.Live API Aktualiséierungen

Versioun 1 groußt nëmmen Nei Saachen addéieren. Mir fuerdergem oder Ëmbenennen wat der schonn ass.

2026-10-08 — Event Resultater eriwwer e E- Stëchwierder. Schéckt et zeréck wéi wann-Keen beschten, fir eng Schnell 304 erofzelueden, wann et näicht geännert gëtt. Optional.
2026-10-08 — Schlësselen am Web elo zesummengezielt all Besucher opzelt an, sou wide Säiten bäibehalen. Keng Aktioun gebraucht.
2026-10-07 — De Client- Zertifikaten (mTLS) sinn op: pixtel däin Zertifikat op engem Schlëssel an dengem Dashboard un. Optional. Keng Aktioun gebraucht.
2026-10-07 — Bulk Feeds: All Évenement d'Duerch an enger Datei, bei GET /v1/bulk. Optional. Keng Aktioun gebraucht.
2026-10-07 — Déi API huet seng Adress: https://api.timtim.live/v1. https://timtim.life/v1 benotzt weider op. Keng Aktioun gebraucht.
2026-10-06 — Är eegen Ofluedsäit bei tim.live/out. Optional. Keng Aktioun gebraucht.
2026-10-06 — Büsten an ärem eegener App verkopen: GET /v1/events/EVENT_ID/tickets an POST /v1/Orderen. Optional. Keng Aktioun gebraucht.
2026-10-06 — Eng öffentlech Statussäit op /partners/Status, iwwerpréift all Minutt. Keng Aktioun gebraucht.
2026-10-06 — Méigleche Beschreiwungen: GET /v1/Besiedelung (Säiten). Keng Aktioun gebraucht.
2026-10-06 — Postbacks: Schéckt ?sub_id= un en Link kafen an mir schécken et zeréck mat der Verlaangen. Optional. Keng Aktioun gebraucht.
2026-10-06 — Fir d'Banken an d'Belønnungeprogrammer: GET /v1/offeren. Optional. Keng Aktioun gebraucht.
2026-10-06 — Feed vun den Kalenner: /v1/feeds/events.ics fir Google Kalenner, Apple-Kalenner an Outlook. Keng Aktioun gebraucht.
2026-10-06 — E Schlëssel op äre Servere spären: IP-Neitlëschten elo, Client-Zertifikaten (mTLS) op api.tim.live. Optional. Keng Aktioun gebraucht.
2026-10-06 — OAuth 2.0 Client Mellinge fir groussen Integratiounen: POST /v1/oauth/token an /v1/eauth/rugegno. Schlësselen sinn ëmmer ugeschalt. Keng Aktioun gebraucht.
2026-10-06 — WordPress Plugin 1.0.0: en Block, en Kortcode an eng Astellungen Säit. Et Aktualiséierungen selwer von tim.liv. Keng Aktioun gebraucht.
2026-10-06 — Website-Widget, JSON/RSS/XML/CSV Feeds an Webhooks (Event.changed, erfolleg.verännert). Keng Aktioun gebraucht.
2026-10-06 — Partner API v1: Events, een Event, Erfolleg, an den Sandbox. Keng Aktioun gebraucht.