API-documentatie

Authenticatie

Elke aanvraag heeft een API key nodig, meegestuurd als bearer token. Je maakt een key aan in het dashboard onder API Keys.

Authorization: Bearer tk_live_...

Alle endpoints hangen onder deze basis-URL:

https://api.talkmarkapp.com/functions/v1

Opnames ophalen

GET /api-v1-recordings

Geeft een lijst met opnames terug, inclusief de bijbehorende transcriptie. Het veld recordings[].transcription.text bevat de volledige tekst, dus met dit ene endpoint kun je alles ophalen zonder webhooks te gebruiken.

curl "https://api.talkmarkapp.com/functions/v1/api-v1-recordings?limit=10&sort=created_desc" \
  -H "Authorization: Bearer tk_live_..."

Wil je periodiek nieuwe opnames ophalen, gebruik dan since met het tijdstip van je vorige aanroep. Dat is de eenvoudigste opzet als je liever niet met webhooks werkt.

Eén transcriptie ophalen

GET /api-v1-transcriptions?id=

curl "https://api.talkmarkapp.com/functions/v1/api-v1-transcriptions?id=TRANSCRIPTIE_ID" \
  -H "Authorization: Bearer tk_live_..."

Het antwoord:

{
  "transcription": {
    "id": "ce1507f3-be01-4713-ae80-b2aab8c212e0",
    "text": "Goedemorgen allemaal, we beginnen met de planning voor het tweede kwartaal...",
    "confidence": 0.94,
    "language": "nl",
    "status": "completed",
    "created_at": "2026-08-10T12:01:58.000Z",
    "recording": {
      "id": "e61c3910-a569-4b22-84c1-9103f006f18a",
      "title": "Klantvergadering Q2 planning",
      "duration_ms": 1800000,
      "audio_url": "https://... (ondertekende link, 1 uur geldig)",
      "audio_url_expires_at": "2026-08-10T13:02:00.000Z"
    },
    "summary": { "summary": "...", "key_points": [], "action_items": [] },
    "insights": { "action_items": [], "decision_points": [], "topics": [] },
    "tags": [],
    "app_url": "https://app.talkmarkapp.com/recordings/e61c3910-..."
  }
}

Webhooks

Een webhook stuurt een HTTP POST naar jouw URL zodra er iets klaar is. Je stelt ze in op de pagina API Keys, onder het kopje Webhooks. Je kunt maximaal tien endpoints registreren.

De payload

De transcripttekst zit bewust niet in de payload, die kan tienduizenden tekens lang zijn. In plaats daarvan krijg je de identifiers en een kant-en-klare URL om de tekst op te halen. Diezelfde velden staan zowel bovenin als in data, zodat elk platform ze kan vinden.

{
  "event": "summary.completed",
  "timestamp": "2026-08-10T12:02:22.534Z",
  "api_version": "2026-03",

  "transcription_id": "ce1507f3-be01-4713-ae80-b2aab8c212e0",
  "recording_id": "e61c3910-a569-4b22-84c1-9103f006f18a",
  "title": "Klantvergadering Q2 planning",
  "transcript_api_url": "https://api.talkmarkapp.com/functions/v1/api-v1-transcriptions?id=ce1507f3-be01-4713-ae80-b2aab8c212e0",

  "data": {
    "recording_id": "e61c3910-a569-4b22-84c1-9103f006f18a",
    "transcription_id": "ce1507f3-be01-4713-ae80-b2aab8c212e0",
    "title": "Klantvergadering Q2 planning",
    "summary": "Bespreking Q2 planning met focus op de offerte en teamcapaciteit.",
    "full_summary": "### Q2-offerte\n...",
    "key_points": ["Offerte moet voor vrijdag klaar"],
    "language": "nl",
    "duration_seconds": 1800,
    "created_at": "2026-08-10T12:02:20.000Z",
    "app_url": "https://app.talkmarkapp.com/recordings/e61c3910-a569-4b22-84c1-9103f006f18a"
  }
}

Handtekening controleren

Elke aflevering krijgt de headers X-TalkMark-Event en X-TalkMark-Signature. Die laatste is een HMAC-SHA256 over de ruwe body, met het secret dat je bij het aanmaken van de webhook te zien kreeg.

import crypto from 'node:crypto';

// body = de RUWE request body, niet het geparste object
function isGeldig(body, signatureHeader, secret) {
  const verwacht = crypto.createHmac('sha256', secret).update(body).digest('hex');
  const ontvangen = (signatureHeader || '').replace(/^sha256=/, '');
  return crypto.timingSafeEqual(Buffer.from(verwacht), Buffer.from(ontvangen));
}

We proberen elke aflevering één keer, met een time-out van tien seconden. Antwoord dus snel met een 200 en doe het echte werk daarna.

Koppelen met Zapier

TalkMark staat nog niet in de Zapier-appdirectory, dus je gebruikt de standaardmodule Webhooks by Zapier. Die zit op een betaald Zapier-plan. Wil je dat vermijden, bekijk dan de Make.com-variant hieronder.

1. Trigger. Maak een Zap met Webhooks by Zapier, optie Catch Hook. Kopieer de URL die Zapier toont.
2. Webhook registreren. Ga naar API Keys, klik op Nieuwe Webhook, plak de URL en kies een event. Neem Samenvatting voltooid als je de samenvatting wilt meesturen, of Transcriptie voltooid als je zo snel mogelijk wilt zijn.
3. Test de trigger. Maak een opname zodat Zapier een echte payload ziet en de velden kan uitlezen.
4. Transcript ophalen. Voeg een actie toe, opnieuw Webhooks by Zapier, methode GET. Kies bij URL het veld transcript_api_url uit stap 1. Voeg één header toe: Authorization met als waarde Bearer gevolgd door je API key. Laat Query String Params helemaal leeg.
5. Doorzetten. Voeg je doel-app toe en koppel het veld transcription__text aan de gewenste plek.

Koppelen met Make.com

Dezelfde opzet, en het gratis plan van Make volstaat. Maak een scenario met Webhooks > Custom webhook, registreer die URL in TalkMark, en zet er een HTTP > Make a request achter met methode GET, de waarde van transcript_api_url als URL, en een header Authorization: Bearer tk_live_.... Make toont geneste velden als een uitklapbare boom, dus daar kies je gewoon het juiste veld.

Doorzetten naar Notion

Wil je alleen handmatig exporteren, gebruik dan de ingebouwde Notion-koppeling onder Integraties. Die zet een opname met samenvatting, actiepunten en het volledige transcript inclusief sprekers in één klik in Notion.

Bouw je het zelf via Zapier of Make, houd dan rekening met twee beperkingen van Notion:

• Een tekstblok mag maximaal 2000 tekens bevatten. Een lang transcript moet dus opgeknipt worden, bijvoorbeeld met de Formatter-stap van Zapier.
• Zet het transcript in de inhoud van de pagina, niet in een database-eigenschap. Die eigenschappen kennen dezelfde tekenlimiet en zijn niet bedoeld voor lange teksten.

Foutmeldingen

Kom je er niet uit? Neem contact op en stuur het tijdstip van je aanvraag mee, dan zoeken we de betreffende aanroep op.