API-dokumentation

/me & /quota

• GET /v1/me : den autentificerede bruger og team-tilhørsforhold.
• GET /v1/quota : aktuelt månedligt forbrug af analyse- og voice-quota.

Eksempel-response for GET /v1/quota :

{
  "data": {
    "analysis": {
      "used": 47,
      "limit": 999999,
      "remaining": 999952,
      "period_start": "2026-05-01",
      "period_end": "2026-05-31"
    },
    "voice": {
      "used": 312,
      "limit": 999999,
      "remaining": 999687,
      "period_start": "2026-05-01",
      "period_end": "2026-05-31"
    },
    "api_fair_use": {
      "used": 1240,
      "limit": 5000,
      "remaining": 3760,
      "period_start": "2026-05-01",
      "period_end": "2026-05-31"
    }
  }
}

analysis tæller email-, transskript- og samtaleanalyser i appen. voice tæller telefon-minutter. api_fair_use er den månedlige fair-use-grænse for API-analyser (fælles pulje pr. team, 1000 pr. seat). Felter er null hvis brugeren ikke har en aktiv periode (fx admin-konto uden loft).

Kontakter

CRUD + merge. DISC-scores er AI-styret og kan ikke skrives via API'et.

• GET /v1/contacts : filtrér med q , primary_type , tag , is_blocked , do_not_call , updated_since .
• GET /v1/contacts/{id}
• POST /v1/contacts → 201 Created
• PATCH /v1/contacts/{id}
• DELETE /v1/contacts/{id} → 204 No Content . Soft delete: sætter deleted_at ; relaterede records bevares.
• POST /v1/contacts/{id}/restore
• POST /v1/contacts/{id}/merge , body: { "target_contact_id": 123 }

Skrivbare felter på POST og PATCH . Mindst ét af name , email eller phone skal være sat på POST .

Eksempel: opret en kontakt.

curl -X POST https://customerflow.dk/api/v1/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anders Andersen",
    "email": "anders@example.com",
    "phone": "+4520202020",
    "company": "Test ApS",
    "tags": ["vip", "inbound"]
  }'

Respons: 201 Created .

{
  "data": {
    "id": 412,
    "user_id": 7,
    "team_id": 3,
    "name": "Anders Andersen",
    "email": "anders@example.com",
    "phone": "+4520202020",
    "company": "Test ApS",
    "cvr_number": null,
    "notes": null,
    "tags": ["vip", "inbound"],
    "is_blocked": false,
    "do_not_call": false,
    "recording_enabled": null,
    "disc": {
      "d_score": null,
      "i_score": null,
      "s_score": null,
      "c_score": null,
      "primary_type": null
    },
    "ai_summary": null,
    "ai_summary_generated_at": null,
    "analysis_count": 0,
    "created_at": "2026-05-21T08:30:00+00:00",
    "updated_at": "2026-05-21T08:30:00+00:00",
    "deleted_at": null
  }
}

DISC-analyser

Read-only. Hver analyse er knyttet til den email eller det opkald der genererede den, og eventuelt en kontakt.

• GET /v1/disc-analyses : filtrér med contact_id , primary_type (D|I|S|C), from , to .
• GET /v1/disc-analyses/{id} : inkluderer dekrypterede reply_suggestions , communication_tips og rationale .

Follow-ups

• GET /v1/follow-ups : filtrér med status (pending |completed |dismissed ), contact_id .
• GET /v1/follow-ups/{id}
• POST /v1/follow-ups → 201 . Body: contact_id (int), suggested_date (i dag eller senere), suggested_message (valgfri).
• POST /v1/follow-ups/{id}/complete
• POST /v1/follow-ups/{id}/dismiss

Conversation insights

Tråd-niveau analyse af email-samtaler: engagement-niveau, sentiment-trend, anbefalet handling.

• GET /v1/conversation-insights : filtrér med contact_id , conversation_id .
• GET /v1/conversation-insights/{id}

Emails

• GET /v1/email-messages : filtrér med contact_id , from , to (ISO 8601 dato), is_analyzed .
• GET /v1/email-messages/{id}

Opkald

Læs opkald inklusiv dekrypteret transskript og taler-diariserede segmenter.

• GET /v1/phone-calls : filtrér med contact_id , direction (outbound |inbound ), status , from , to .
• GET /v1/phone-calls/{id} : inkluderer segments[] med taler-label, tekst og start/slut i millisekunder.

Analyse (ephemeral)

POST tekst til AI-analyse uden persistens. Hver succesfuld request tæller som ét forbrug af teamets månedlige fair-use-grænse (1000 pr. seat). Ved upstream-timeout (504) eller -fejl (502) forbruges intet.

• POST /v1/analyze/email , body: { "text": "..." } (min 20, max 50.000 tegn) → DISC-scores + reply_suggestions.
• POST /v1/analyze/transcript , body: { "text": "..." } (min 20, max 200.000 tegn) → DISC fra samtale.
• POST /v1/analyze/conversation , body: { "emails": [...] } (min 2, max 50 emails, hver body min 10 og max 50.000 tegn, total max 200 KB) → engagement, sentiment, summary.
• POST /v1/analyze/follow-up-suggestion , body: { "disc_type": "D|I|S|C", "context": "..." } (context min 20, max 5.000 tegn) → besked + dato-forslag.

Eksempel:

curl -X POST https://customerflow.dk/api/v1/analyze/email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Vi skal have lukket dealen denne uge. Send tilbud nu."}'

Respons (200 OK):

{
  "data": {
    "d_score": 65,
    "i_score": 15,
    "s_score": 10,
    "c_score": 10,
    "primary_type": "D",
    "confidence_score": 88,
    "rationale": "Direkte handlingsorienteret formulering...",
    "communication_tips": ["Vær kort", "Lever bottom line først"],
    "reply_suggestions": {
      "short": "Tilbud er på vej i dag.",
      "neutral": "Tak. Jeg sender et tilbud i løbet af dagen.",
      "detailed": "Tak for opfølgningen. Tilbuddet er klar..."
    }
  }
}

Opret og administrér

Webhooks kan oprettes via UI'et (Indstillinger . API . Webhooks) eller via API'et:

• GET /v1/webhooks : listing.
• POST /v1/webhooks → 201 . Body: name (max 80), url (HTTPS, max 2048), events (array, mindst én). Returnerer signing_secret i plaintext én gang.
• GET /v1/webhooks/{id} : detail. Indeholder ikke signing_secret.
• PATCH /v1/webhooks/{id} : opdatér name , url , events eller is_active .
• DELETE /v1/webhooks/{id} → 204 .
• POST /v1/webhooks/{id}/test : sender et ping -event. Test-leveringer tæller ikke mod auto-disable.
• POST /v1/webhooks/{id}/rotate-secret : genererer ny signing_secret og invaliderer den gamle øjeblikkeligt. Responsen har samme shape som POST og inkluderer det nye secret én gang.
• GET /v1/webhooks/{id}/deliveries : paginated leveringslog (status, response-kode, retry-tidspunkter).

Eksempel: opret en webhook der lytter på flere events.

curl -X POST https://customerflow.dk/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mit CRM",
    "url": "https://din-server.dk/webhooks/customerflow",
    "events": ["contact.created", "contact.updated", "disc.analysis.created"]
  }'

Respons (201 Created ):

{
  "data": {
    "id": 18,
    "user_id": 7,
    "team_id": 3,
    "name": "Mit CRM",
    "url": "https://din-server.dk/webhooks/customerflow",
    "events": ["contact.created", "contact.updated", "disc.analysis.created"],
    "is_active": true,
    "consecutive_failed_deliveries": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "auto_disabled_at": null,
    "auto_disabled_reason": null,
    "created_at": "2026-05-21T08:30:00+00:00",
    "signing_secret": "a1b2c3d4e5f6...64-hex"
  }
}

Event-typer

Privacy-noter: forceDelete() (GDPR-purge) fyrer ALDRIG contact.deleted . Slettet kontakt slettes tavst. Restore-flow fyrer præcis ét contact.updated , ikke to.

Payload-eksempler

Hver POST har Content-Type: application/json . Body følger de eksempler vist nedenfor. Ukendte felter kan dukke op i fremtidige versioner. Ignorér dem.

contact.created · contact.updated

{
  "id": 412,
  "user_id": 7,
  "team_id": 3,
  "name": "Anders Andersen",
  "email": "anders@example.com",
  "phone": "+4520202020",
  "company": "Test ApS",
  "tags": ["vip"],
  "is_blocked": false,
  "do_not_call": false,
  "disc": {
    "d_score": 40,
    "i_score": 30,
    "s_score": 20,
    "c_score": 10,
    "primary_type": "D"
  },
  "deleted_at": null,
  "created_at": "2026-05-21T08:30:00+00:00",
  "updated_at": "2026-05-21T08:30:00+00:00"
}

contact.deleted (PII-trimmet)

{
  "id": 412,
  "deleted_at": "2026-05-21T09:45:00+00:00"
}

disc.analysis.created

{
  "id": 5821,
  "user_id": 7,
  "contact_id": 412,
  "email_message_id": 11023,
  "phone_call_id": null,
  "d_score": 40,
  "i_score": 30,
  "s_score": 20,
  "c_score": 10,
  "primary_type": "D",
  "confidence_score": 85,
  "rationale": "Direkte, handlingsorienteret sprog...",
  "communication_tips": ["Vær kort", "Lever bottom line først"],
  "reply_suggestions": {
    "short": "Tak. Send tilbud i dag.",
    "neutral": "Tak. Jeg sender et tilbud i løbet af dagen.",
    "detailed": "Tak for opfølgningen. Tilbuddet er klar..."
  },
  "created_at": "2026-05-21T08:30:00+00:00"
}

call.completed

{
  "id": 9011,
  "user_id": 7,
  "contact_id": 412,
  "direction": "outbound",
  "from_number": "+4570201020",
  "to_number": "+4520202020",
  "status": "completed",
  "duration_seconds": 187,
  "started_at": "2026-05-21T08:25:00+00:00",
  "ended_at":   "2026-05-21T08:28:07+00:00",
  "transcript": "A: Hej Anders, har du tid til en kort snak?\nB: Ja, hvad drejer det sig om?\n...",
  "transcript_truncated": false,
  "is_analyzed": true
}

Andre events (follow_up.created , follow_up.completed , email.analyzed , conversation.insight.created ) følger samme principper. Webhook-payloads er en kurateret undermængde af det tilsvarende GET -endpoint - fx udelades segments , recording_consent og voice_minutes_charged fra call.completed . Ukendte felter kan dukke op i fremtidige versioner - ignorér dem.

Verificér signatur

Hver POST kommer med følgende headers:

X-CustomerFlow-Signature: t=1716200000,v1=4d8b3a...
X-CustomerFlow-Event: contact.created
X-CustomerFlow-Delivery: 0fcc77b8-2f6a-4f25-9c39-9ea1c2bc7e15
Content-Type: application/json

Genberegn HMAC-SHA256 over "<t>.<raw-body>" med din signing-secret og sammenlign konstanttidsmæssigt. Afvis hvis tidsstempel er mere end 5 minutter gammelt. Det er replay-vinduet.

PHP

function verify(string $body, string $header, string $secret): bool {
    if (! preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m)) {
        return false;
    }
    [, $t, $v1] = $m;
    if (abs(time() - (int)$t) > 300) return false;
    $expected = hash_hmac('sha256', $t . '.' . $body, $secret);
    return hash_equals($expected, $v1);
}

Node.js

import crypto from 'node:crypto';

function verify(body, header, secret) {
  const match = header.match(/t=(\d+),v1=([a-f0-9]+)/);
  if (!match) return false;
  const [, t, v1] = match;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(v1, 'hex'),
  );
}

Levering & idempotens

• Asynkron: leveringer sendes via en baggrundskø, så der kan gå et øjeblik fra eventet sker til din endpoint kaldes.
• At-least-once: pga. retries kan du modtage samme levering mere end én gang. Dedupér på X-CustomerFlow-Delivery (unik UUID pr. levering) og spring leveringer over du allerede har behandlet. Gør din handler idempotent.
• Svar hurtigt: vi venter højst 10 sekunder på et svar. Svar 2xx med det samme og processér tungt arbejde bagefter - ellers tæller det som timeout og udløser en retry (og dermed en dublet).
• Ingen rækkefølge-garanti: events leveres ikke nødvendigvis i den rækkefølge de skete. Brug tidsstemplerne i payloaden hvis rækkefølge er vigtig.
• Redirects følges ikke: peg url direkte på din endelige endpoint. Et 3xx -svar behandles som en mislykket levering.

Retry & auto-disable

• 2xx: leveringen markeres som success .
• 5xx, 408, 429 eller netværksfejl: retry med backoff [1m, 5m, 30m, 2h, 12h] . Efter 5 mislykkede forsøg markeres leveringen dead .
• Andre 4xx (400, 401, 403, 404, 422): failed uden retry. Det er en consumer-fejl, og retry hjælper ikke.
• Auto-disable: hvis en webhook er ældre end 48 timer, har 25+ fejlede leveringer i træk OG ingen succesfuld levering de seneste 24 timer, deaktiveres den automatisk. Test-leveringer påvirker ikke tælleren.