Skip to content

Kontakt API

The Kontakt API lets your backend send people, events, leads, orders, and consent into Kontakt, and work with wallets, codes, and referrals. Everything on this page applies to every endpoint.

Use the API when your own systems hold the data Kontakt needs: sign-ups, purchases, account changes, or form submissions. Events you send start journeys, update audiences, and give AI agents context, the same way events from Shopify or webhook sources do.

For the full list of fields on every endpoint, see the API reference.

Base URL

https://api.usekontakt.com/v1

All requests use HTTPS. Request and response bodies are JSON.

Get an API key

You need a role that can change workspace settings.

Open API Keys

Go to Settings / API Keys and click Create API Key.

Name the key

Enter a Key name that says where it is used, such as Production backend. Use a separate key for each system that sends data, so you can switch one off or rotate it without affecting the others.

Copy the key

Click Create API Key. Copy the key from API Key Ready with Copy to Clipboard and store it in your secrets manager. Kontakt shows it only once. Tick I have saved this API key securely and click Close.

The API Keys page in Settings with the API Access card and the public API base URL

Keys start with pk_live_. A key belongs to one workspace and can call every endpoint on this page. There is no separate test mode, so every call changes real data. To experiment safely, create a second workspace for testing and use a key from it. See Workspaces.

Rotate or delete a key

Open the key's menu on the API Keys page:

  • Rotate issues a new key and stops the old one immediately. Update your systems right away.
  • Delete removes the key for good. Type DELETE to confirm.

Authenticate

Send the key as a bearer token in the Authorization header on every request:

curl https://api.usekontakt.com/v1/ping \
  -H "Authorization: Bearer pk_live_your_key"
{ "status": "ok" }

GET /v1/ping checks that your key works. It needs the key like every other endpoint and counts toward the key's rate limit.

ProblemStatusError code
Header missing, key wrong, rotated, or deleted, or the workspace is not active401UNAUTHORIZED
A dashboard session token was used instead of an API key403FORBIDDEN

Endpoints

AreaEndpoints
PeoplePOST /customers, POST /identify, POST /customers/{id}/devices
Events and leadsPOST /events, POST /leads
CommercePOST /orders
ConsentPOST /consent
WalletsGET /customers/{id}/wallet, POST /customers/{id}/wallet/credit, POST /customers/{id}/wallet/debit, GET /customers/{id}/wallet/transactions
CodesPOST /codes/validate, GET /codes/code-batches/{id}/stats
ReferralsGET /customers/{id}/referral, POST /referrals/attribute
SMSGET /sms/senders
HealthGET /ping

{id} is always the Kontakt customer ID, the id returned by POST /customers. When to use each ingestion endpoint is covered in Ingestion.

Requests

  • Send Content-Type: application/json on every request with a body.
  • Bodies can be up to 1 MB.
  • Send phone numbers in E.164 format, such as +2348030000000.
  • Send timestamps in ISO 8601, such as 2026-10-22T09:30:00Z.

Responses

Successful responses wrap the result in data and add a request ID in meta:

{
  "data": {
    "event_id": "8a1f0c3e-6b7d-4c51-9a8e-2f4d1b0c9e77",
    "customer_id": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28",
    "event_name": "plan.upgraded",
    "properties": { "plan": "pro" },
    "timestamp": "2026-10-22T09:30:00.000Z",
    "customer_created": false,
    "warnings": []
  },
  "meta": { "request_id": "5d0b8f7e-2a41-4c9b-b0e3-7f1c6a2d9e54" }
}

Every response also carries an X-Request-Id header with the same value. Send your own X-Request-Id header to use your ID instead. Include the request ID when you contact support.

GET /ping is the one exception: it returns {"status": "ok"} without the data wrapper.

Errors

Errors use one shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "event is required and must be a string",
    "details": {}
  },
  "meta": { "request_id": "5d0b8f7e-2a41-4c9b-b0e3-7f1c6a2d9e54" }
}
StatusCodeMeaning
400INVALID_JSONThe body isn't valid JSON
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENNot authenticated with an API key
404NOT_FOUNDThe person or resource doesn't exist, or the path is wrong
413PAYLOAD_TOO_LARGEThe body is over 1 MB
422VALIDATION_ERRORA field is missing or invalid, or identities conflict. message says which.
429RATE_LIMIT_EXCEEDEDThis API key is over 1,000 requests per minute. Wait for the Retry-After header's seconds, then retry. See Rate limits.
500INTERNAL_ERRORSomething went wrong on our side. Retry with backoff.

Treat any 5xx as retryable and any 4xx other than 429 as a problem to fix before retrying.

Wallet and code endpoints

The wallet and code endpoints return some errors in a shorter form. Check the status code first, then read error as a string:

EndpointStatusBody
Wallet credit or debit with an invalid field400{"error": "<what is wrong>"}
Wallet debit with too few points422{"error": "Insufficient balance", "current_balance": 40, "required": 100}
POST /codes/validate with an invalid field400{"error": "<what is wrong>"}
Code batch stats for an unknown batch404{"error": "Batch not found"}

Accepted but ignored: 202

If a workspace admin switched off your API key, or one event from it, under Events / Sources, POST /events, POST /leads, and POST /orders answer 202 and record nothing:

{ "data": { "event_name": "lead_captured", "ignored": true, "reason": "event_off" }, "meta": { "request_id": "..." } }

reason is source_off when the whole key is off and event_off when only that event is. Don't retry these. Ask the workspace admin to switch the source back on if it was a mistake.

Idempotency

Retrying a request should never create duplicates. These fields make retries safe:

EndpointHow to make it safe to retry
POST /events, POST /leadsSend idempotency_key. A repeat returns 200 with "deduplicated": true and the original event_id. Keys are unique across your whole workspace, so include the event type in them.
POST /ordersOrders are matched on store_id and order_id. Sending the same order again updates it instead of adding a second one.
POST /customersMatched on customer_id, user_id, email, or phone, so repeats update the same person.
Wallet credit and debitSend idempotency_key. A repeat returns the original transaction instead of moving points again.

Pagination

GET /customers/{id}/wallet/transactions is the only list endpoint. Page with limit (default 50, maximum 200) and offset. The response includes:

"meta": {
  "request_id": "...",
  "pagination": { "total": 128, "limit": 50, "has_more": true }
}

Increase offset by limit until has_more is false.