Partner API — Snabbstart

Din första integration får plats på en skärm.

Prova nu — ingen nyckel, ingen registrering

Öppna den här adressen i din webbläsare. Du ser exempelevenemang direkt.

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

1
Hämta en testnyckel
Logga in, berätta vem du är och tryck på Skapa testnyckel. Den börjar med tt_test_ och ser bara exempelevenemang.

Hitta evenemang

Be om evenemang i en stad.

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

3
Visa evenemanget
Varje evenemang har namn, datum, plats, bild, pris och färdiga etiketter till ditt kort.
4
Använd buy_url
Använd den buy_url vi ger dig. Klart. TimTim.Live håller reda på var köpet kom ifrån inuti länken.
5
Se resultat
Se hur många du skickat, sålda biljetter och intäkter i din översikt, eller be om dem.
GET https://api.timtim.live/v1/earnings

Hämta min testnyckel Testa utan nyckel

TimTim.Live-status

Referens

Vart du skickar förfrågningar

https://api.timtim.live/v1

Din anslutningsnyckel

Skicka din nyckel i Authorization-huvudet. Testnycklar (tt_test_) ser bara exempelevenemang. Webbplatsnycklar (tt_pk_live_) kan ligga på en webbsida och läser bara evenemang. Servernycklar (tt_sk_live_) stannar på din server och kan även läsa intäkter. Vi visar en nyckel en gång — förvara den säkert.

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: Evenemang i den här staden.
country: Landskod med två bokstäver, till exempel US.
category: Till exempel musik, festival eller konferens.
from: Evenemang på eller efter det här datumet (2026-10-20).
to: Evenemang på eller före det här datumet.
changed_since: Bara evenemang som ändrats efter den här tiden.
commissioned: true = bara evenemang som ger en belöning.
minimum_earnings: Bara evenemang som betalar minst så här mycket per biljett.
near: En plats, till exempel near=Paris,FR.
limit: Hur många evenemang per sida, 1 till 100 (20 om du inte anger något).

Berätta bara vad som ändrats

Spara tiden för din senaste synk och skicka den som changed_since. Du får bara evenemang som ändrats — även inställda och slutsålda. Ingen webhook behövs. Evenemang som du ska sluta visa kommer i listan withdrawn.

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

Mer än en sida

Om svaret har next, skicka tillbaka det som cursor= för att få nästa sida. När next är tomt har du allt.

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

Intäkter

Varje evenemang har earn. Om earn.eligible är false har evenemanget ingen belöning — det är ändå värt att visa. Om det är true säger earn.description vad du får, till exempel ”$5 per behörig biljett”. Om köpet återbetalas dras belöningen tillbaka.

Bulkflöden (allt i en fil)

Spara ett bulkflöde i din översikt och ladda sedan ner alla dess evenemang i en komprimerad fil: GET /v1/bulk/FEED_ID.ndjson.gz eller .csv.gz, med din servernyckel. Lägg till ?changed_since= för bara ändringarna, även borttagna evenemang. Testnycklar kan prova det nu; riktig användning kräver en granskning från TimTim.Live.

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

Sälj biljetter i din egen app (inbyggd handel)

Stora partner kan hålla köparna kvar i sin egen app. Fråga GET /v1/events/EVENT_ID/tickets vad som säljs, och skicka sedan POST /v1/orders med köparens val. Du får en betalningslänk från TimTim.Live som du öppnar för köparen; försäljningen krediteras direkt till ditt företag. Testnycklar kan prova det nu. Riktig användning kräver en granskning från TimTim.Live och att kortbetalningar är påslagna.

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

Kortkopplade erbjudanden (banker och belöningsprogram)

GET /v1/offers ger varje evenemang som betalar en belöning som ett erbjudande: arrangören, datumen man kan köpa, priset, platsen och belöningen. Din kund aktiverar det via din spårade länk, och belöningen betalas till ditt företag via /v1/earnings. Testnycklar ser exempelerbjudanden. Riktiga erbjudanden behöver en granskning av TimTim.Live. Att matcha kortbetalningar direkt kräver ett avtal med ett kortnätverk eller en bank, och det är inte anslutet.

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

Evenemangsstatus och biljetter

status är scheduled, postponed, rescheduled, cancelled, sold_out eller completed. tickets.availability är available, limited, sold_out, not_on_sale eller ended. När ett evenemang ställs in, ta bort det.

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

Hur snabbt du kan fråga

Testnycklar: 60 förfrågningar i minuten. Livenycklar: 120 i minuten. Går du snabbare får du svaret 429 med Retry-After, alltså hur många sekunder du ska vänta.

Vilka evenemang du får

Evenemang som arrangörer på TimTim.Live skapar och väljer att dela. Evenemang som vi hämtat från andra biljettsajter tas aldrig med, eftersom vi inte har rätt att dela dem.

Det här skickar vi aldrig

Köparnas namn, e-postadresser, hemadresser, telefonnummer och kortuppgifter. Partner API delar information om evenemang, inte om våra medlemmar.

Webbplatswidget

En rad HTML visar evenemang på vilken webbplats som helst. Använd en webbplatsnyckel (tt_pk_live_) och lägg till din webbplats i nyckelns lista över tillåtna webbplatser. Utan nyckel visar den exempelevenemang.

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

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

OAuth 2.0 (stora integrationer)

Valfritt. Skapa en OAuth-klient i din översikt. Byt sedan dess klient-id och hemlighet mot en åtkomsttoken som gäller i en timme, och skicka den token i stället för en nyckel. Hemligheten följer aldrig med dina API-anrop, och du kan be om färre behörigheter (scopes) än klienten har.

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

Vill du stoppa en token tidigare, skicka den med POST till /v1/oauth/revoke med samma klient-id och hemlighet. Stänger du av klienten i din översikt slutar alla dess tokens att gälla på en gång.

Lås en nyckel till dina servrar

Valfritt. Öppna "Lås till mina servrar" i din översikt under en servernyckel, testnyckel eller OAuth-klient och skriv dina servrars offentliga adresser. Anrop — och token-förfrågningar — från alla andra ställen nekas med ip_not_allowed, även med rätt nyckel.

Klientcertifikat (mTLS): koppla ditt TLS-klientcertifikat till en nyckel och anropa sedan https://api.timtim.live med det. Varje anrop måste visa det certifikatet; TLS-handskakningen bevisar att du har dess privata nyckel.

# 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-tillägg

Använder du WordPress? Installera TimTim.Live Events: ett block och en kortkod som visar evenemang med dina egna biljettlänkar från TimTim.Live. Det är gjort av TimTim.Live, pratar bara med timtim.live och uppdateras bara från timtim.live.

Ladda upp filen under Tillägg → Lägg till nytt → Ladda upp tillägg. Klistra in din webbplatsnyckel under Inställningar → TimTim.Live Events och tryck på Test Connection. Lägg sedan till blocket TimTim.Live Events på valfri sida.

Ladda ner WordPress-tillägget

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

Flöden

Samma evenemang som JSON Feed, RSS, XML, CSV eller en kalender (.ics) som Google Calendar, Apple Calendar och Outlook kan prenumerera på. Flödesläsare kan inte skicka huvuden, så lägg en webbplatsnyckel eller en testnyckel i ?key=. Lägg aldrig en servernyckel i en länk.

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

Tryck på ”Lägg till adress” på din kontrollpanel, så skickar vi ett meddelande dit när något ändras: event.changed eller earnings.changed. Webhooks är frivilliga — changed_since ger dig samma information.

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

Kontrollera varje meddelande: det är signerat med din hemlighet. Avvisa allt som är äldre än fem minuter, och ignorera ett TimTim-Delivery-Id som du redan har hanterat.

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

Svara med valfri 2xx inom 10 sekunder. Annars försöker vi igen efter 1 minut, 5 minuter, 30 minuter, sedan efter 2, 6, 12 och 24 timmar, och slutar sedan. Vi följer aldrig omdirigeringar.

Sandlådan

Testnycklar får exempelevenemang märkta TESTEVENEMANG — INGA RIKTIGA PENGAR. Öppna en buy_url, tryck på Köp testbiljett och be sedan om dina intäkter. Testa en återbetalning och se den dras tillbaka.

När något går fel

Felmeddelanden förklarar sig själva med enkla ord, med en rubrik och vad du ska göra sedan. Varje svar har ett TimTim-Request-Id. Skicka det till oss så kan vi hitta din förfrågan.

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.

Avtalet

En fullständig beskrivning av varje fält, i OpenAPI-format som dina verktyg kan läsa.

Ladda ner openapi.yaml

Så öppnas skarpa nycklar

Din testnyckel fungerar direkt. För skarpa nycklar tittar en person på TimTim.Live på ditt företagsnamn, din webbplats och hur du ska visa evenemang. Svaret ser du i din översikt.

Uppdateringar av TimTim.Live API

Version 1 växer bara. Vi lägger till nya saker. Vi tar inte bort eller byter namn på det som redan finns.

2026-10-08 — Svar om evenemang har nu en ETag. Skicka tillbaka den i If-None-Match för att få ett snabbt 304 när inget har ändrats. Valfritt.
2026-10-08 — Webbplatsnycklar räknar nu varje besökare för sig, så att välbesökta webbplatser fortsätter att fungera. Du behöver inte göra något.
2026-10-07 — Klientcertifikat (mTLS) är öppna: koppla ditt certifikat till en nyckel i din översikt. Valfritt. Du behöver inte göra något.
2026-10-07 — Bulkflöden: alla evenemang du får visa, i en fil, på GET /v1/bulk. Valfritt. Du behöver inte göra något.
2026-10-07 — API:et har en egen adress: https://api.timtim.live/v1. https://timtim.live/v1 fortsätter att fungera. Inget behöver göras.
2026-10-06 — Din egen kassasida med ditt varumärke på timtim.live/checkout. Valfritt. Du behöver inte göra något.
2026-10-06 — Sälj biljetter i din egen app: GET /v1/events/EVENT_ID/tickets och POST /v1/orders. Valfritt. Du behöver inte göra något.
2026-10-06 — En öppen statussida på /partners/status, kontrolleras varje minut. Du behöver inte göra något.
2026-10-06 — Månadsrapporter för företag: GET /v1/settlements. Du behöver inte göra något.
2026-10-06 — Postbacks: lägg till ?sub_id= i en köplänk så skickar vi tillbaka det till dig med försäljningen. Valfritt. Du behöver inte göra något.
2026-10-06 — Kortkopplade erbjudanden för banker och belöningsprogram: GET /v1/offers. Valfritt. Du behöver inte göra något.
2026-10-06 — Kalenderflöde: /v1/feeds/events.ics för Google Calendar, Apple Calendar och Outlook. Du behöver inte göra något.
2026-10-06 — Lås en nyckel till dina servrar: listor över tillåtna IP-adresser nu, klientcertifikat (mTLS) på api.timtim.live. Valfritt. Du behöver inte göra något.
2026-10-06 — OAuth 2.0 client credentials för stora integrationer: POST /v1/oauth/token och /v1/oauth/revoke. Nycklar fungerar fortfarande. Du behöver inte göra något.
2026-10-06 — WordPress-tillägg 1.0.0: ett block, en kortkod och en inställningssida. Det uppdaterar sig självt från timtim.live. Du behöver inte göra något.
2026-10-06 — Webbplatswidget, JSON/RSS/XML/CSV-flöden och webhooks (event.changed, earnings.changed). Du behöver inte göra något.
2026-10-06 — Partner API v1: evenemang, ett evenemang, intäkter och sandlådan. Du behöver inte göra något.