Core concepts

Idempotency

Networks fail and CRMs retry. An idempotency key lets you send the same event twice and get one Video Intro.

How it works

Send an Idempotency-Key header on every request that creates something.

You send	You get
A key for the first time	The request is processed. `accepted`
The same key with the same body	The original result, marked `duplicate`. Nothing new is created.
The same key with a different body	`409 idempotency_conflict`

Make the key deterministic

Build the key from facts that identify the moment, so a retry produces the same key without you storing anything:

Pattern

source : record id : touchpoint
your_crm:appointment_123:new_appointment

Never use a random value or a timestamp. A retry would look like a new event.
If one record can reach the same touchpoint more than once, add what makes each time different, for example the trade: acculynx:job_5490:project_update:roofing

Retrying

Retry on a timeout, a 429 or a 5xx, with the same key. Do not retry a 4xx other than 429: the request needs to change.

Headers

POST /v1/touchpoint-events
Authorization: Bearer vi_test_••••••••••••
Idempotency-Key: your_crm:appointment_123:new_appointment
Content-Type: application/json

Second time · same key, same body

{
  "id": "evt_8f3c2a71d04e",
  "object": "touchpoint_event",
  "status": "duplicate",
  "touchpoint": "new_appointment",
  "environment": "test",
  "created_at": "2026-10-05T17:40:01Z"
}

Same key, different body · 409

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different body."
  }
}