Skip to content

Ingestion

Six endpoints bring data into Kontakt. This page explains when to use each one, what it changes, and what it returns.

All examples use the base URL https://api.usekontakt.com/v1 and a key from Settings / API Keys. Response bodies below show the data object; every response also has meta.request_id. See Kontakt API for authentication, errors, and idempotency.

Which endpoint to use

You want toEndpoint
Create or update a person's profilePOST /customers
Record something a person did, and start journeysPOST /events
Capture a form submission or sign-up leadPOST /leads
Merge an anonymous visitor into a known personPOST /identify
Record an order from a store Kontakt isn't connected toPOST /orders
Record a subscribe or unsubscribe for a channelPOST /consent
Register a phone for push notificationsPOST /customers/{id}/devices

POST /events can also create and update the person, so many integrations only need that one endpoint.

How Kontakt finds the person

Every endpoint matches the person in this order and uses the first match:

  1. customer_id: the Kontakt ID returned by earlier calls.
  2. user_id: your own ID for the person. Kontakt stores it and shows it as the person's user ID.
  3. email: an exact match, so send emails in one consistent format, such as lowercase.
  4. phone: E.164, such as +2348030000000, is best.
  5. anonymous_id: an ID Kontakt issued for an anonymous visitor.

Phone numbers without a country code. Kontakt saves every phone in E.164 so it matches the number WhatsApp and SMS replies come from. A number such as 08030000000, 8030000000, or 2348030000000 gets the workspace's country code. Set the country under Settings / Workspaces by editing the workspace and choosing Country for local phone numbers. If no country is set, Kontakt uses the workspace timezone, so Africa/Lagos means Nigeria. If a person was saved earlier with the number in its local form, Kontakt moves them to the E.164 form the next time that number arrives, unless someone already has it.

If you send customer_id together with an email, phone, or user ID that already belongs to someone else, Kontakt rejects the call with 422 rather than merging two people.

Customers

POST /customers creates or updates a profile.

curl -X POST https://api.usekontakt.com/v1/customers \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_1042",
    "email": "ada@example.com",
    "phone": "+2348030000000",
    "properties": { "first_name": "Ada", "last_name": "Obi", "plan": "pro" },
    "consent": [{ "channel": "whatsapp", "status": "subscribed" }]
  }'

Returns 201 for a new person and 200 for an existing one:

{
  "id": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28",
  "user_id": "usr_1042",
  "email": "ada@example.com",
  "phone": "+2348030000000",
  "properties": { "first_name": "Ada", "last_name": "Obi", "source": "api", "status": "active", "plan": "pro" },
  "created_at": "2026-10-22T09:30:00.000Z",
  "updated_at": "2026-10-22T09:30:00.000Z"
}
  • Properties. These keys update profile fields: first_name, last_name, avatar_url, tier, country, region, city, area. Any other key becomes a custom field and is merged with existing custom fields. See Fields and tags.
  • Identity fields only fill gaps. A top-level user_id, email, or phone is saved only when the person doesn't have one yet.
  • Tags. tags (or add_tags) adds tags and remove_tags removes them. Send an array or a comma-separated string, up to 50 at a time. Tags that don't exist yet are created. When you send either, the response includes tags with the person's full list.
  • Consent. Each consent entry needs a channel (whatsapp, sms, email, or rcs) and a status (subscribed, unsubscribed, or unknown).
  • Anonymous visitors. Send no identity at all and Kontakt creates an anonymous person and returns an anonymous_id starting with anon_. Store it in your app and send it with later events and with POST /identify.

Events

POST /events records an event on a person. Journeys triggered by that event name start, journeys waiting for it resume, and audiences update.

curl -X POST https://api.usekontakt.com/v1/events \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_1042",
    "event": "plan.upgraded",
    "properties": { "plan": "pro", "amount": 49 },
    "traits": { "first_name": "Ada" },
    "tags": ["pro_customer"],
    "timestamp": "2026-10-22T09:30:00Z",
    "idempotency_key": "plan.upgraded:usr_1042:2026-10-22"
  }'

Returns 201:

{
  "event_id": "8a1f0c3e-6b7d-4c51-9a8e-2f4d1b0c9e77",
  "customer_id": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28",
  "event_name": "plan.upgraded",
  "properties": { "plan": "pro", "amount": 49 },
  "timestamp": "2026-10-22T09:30:00.000Z",
  "customer_created": false,
  "warnings": [],
  "tags": ["pro_customer"]
}
FieldRequiredNotes
eventYesThe event name journeys trigger on
customer_id, user_id, email, phone, or anonymous_idAt least oneSee How Kontakt finds the person
propertiesNoEvent details, available to journey conditions and messages
traitsNoProfile updates, using the same keys as customer properties. Empty strings are ignored. whatsapp_opt_in: false opts the person out of WhatsApp marketing.
timestampNoWhen it happened. Defaults to now.
tags, remove_tagsNoTags to add or remove, as an array or comma-separated string. add_tags also works. The response then includes tags.
idempotency_keyNoA repeat returns 200 with "deduplicated": true. If the body has none, Kontakt reads the Idempotency-Key header, then X-CIO-Idempotency-Key, which Customer.io webhooks send on every retry.
upsert_customerNoDefault true: create the person if no one matches. Set false to only record events for existing people.

warnings contains phone_conflict when the phone you sent belongs to a different person. The event is still recorded, and the phone is not moved.

With upsert_customer: false and no match, the call fails with 422.

Leads

POST /leads captures a form submission. It creates or updates the person and records a lead_captured event. It does not open a conversation. Build a journey triggered by lead_captured to reach out. See Journeys.

curl -X POST https://api.usekontakt.com/v1/leads \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Obi",
    "email": "ada@example.com",
    "phone": "+2348030000000",
    "form_id": "pricing-demo",
    "form_name": "Book a demo",
    "fields": { "company": "Brightway", "team_size": "11-50" },
    "attribution": { "source": "google", "medium": "cpc", "campaign": "q4-demo" },
    "idempotency_key": "lead:pricing-demo:7781"
  }'

Returns 201 with event_id, customer_id, event_name (lead_captured), properties, timestamp, and conversation_id.

  • Name, email, phone, and user ID are saved only if the person doesn't have them yet. name is split into first and last name.
  • fields are merged into custom fields. form_id and form_name are saved as custom fields too.
  • attribution accepts source, medium, campaign, content, term, ad_id, and landing_page, and is kept as the person's first touch.
  • Form tool payloads. You can post a form tool's webhook body as is. Kontakt unwraps data, payload, form_response, or submission, reads field arrays with labels and values, finds email and phone fields by their labels, and picks up hidden UTM fields such as utm_source.
  • If no email, phone, user ID, or customer ID can be found, the call fails with 422.

Identify

POST /identify links an anonymous visitor to a known person, typically at sign-up or login.

curl -X POST https://api.usekontakt.com/v1/identify \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymous_id": "anon_5f2c9a0e7b1d4c6a8e3f0b2d9c7a1e44",
    "user_id": "usr_1042",
    "email": "ada@example.com",
    "properties": { "first_name": "Ada" }
  }'

Returns 200:

{
  "id": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28",
  "user_id": "usr_1042",
  "email": "ada@example.com",
  "properties": { "first_name": "Ada" },
  "events_merged": 12
}
  • If a person with that user ID, email, or phone already exists, Kontakt moves the anonymous visitor's events to them, merges custom fields, and removes the anonymous record. events_merged says how many events moved.
  • Otherwise the anonymous record becomes the known person.
  • Send referred_by_code with a referral code to credit the referrer. See Referrals.
  • An unknown anonymous_id returns 404. Only anonymous_id values issued by Kontakt work.

Orders

POST /orders records an order from any store. It feeds the same purchase history, computed fields, journeys, and attribution as a connected Shopify store. If your store is connected through Shopify, you don't need this.

curl -X POST https://api.usekontakt.com/v1/orders \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "main-web-store",
    "store_name": "Main web store",
    "order_id": "100245",
    "external_customer_id": "usr_1042",
    "email": "ada@example.com",
    "phone": "+2348030000000",
    "total": 125.50,
    "subtotal": 110.00,
    "currency": "USD",
    "financial_status": "paid",
    "fulfillment_status": "unfulfilled",
    "discount_codes": ["WELCOME10"],
    "landing_url": "https://shop.example.com/?utm_campaign=q4",
    "ordered_at": "2026-10-22T09:30:00Z",
    "items": [{ "product_id": "sku-1", "title": "Trail shoe", "sku": "TS-42", "quantity": 1, "price": 110.00 }]
  }'

Returns 201. Note that this response uses camelCase keys, and orderId is Kontakt's ID for the order:

{ "orderId": "b7e1c2d4-9a3f-4e6b-8c1d-2f5a7e9b0c13", "customerId": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28" }
  • Required: store_id, order_id, and total. store_id is your own name for the store; Kontakt creates the store the first time it sees it.
  • Retries and updates. Orders are matched on store_id and order_id. Send the same order again with a new financial_status or fulfillment_status to update it.
  • Events. A new order records commerce.order_placed. Changing financial_status to paid records commerce.order_paid. Changing fulfillment_status to fulfilled records commerce.order_fulfilled.
  • Linking the person. Send email, phone, or external_customer_id. Without any of them the order is stored but not linked to anyone, and no events are recorded.
  • Test orders. Set "test": true to store an order without events.
  • Attribution. Discount codes and the landing URL are used to credit the order to a Kontakt message. See Shopify attribution.

POST /consent records a subscribe or unsubscribe for one channel.

curl -X POST https://api.usekontakt.com/v1/consent \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+2348030000000", "channel": "sms", "status": "unsubscribed" }'

Returns 200:

{ "customer_id": "3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28", "channel": "sms", "status": "unsubscribed" }
  • Identify the person with customer_id, user_id, email, or phone. Consent never creates a person; an unknown person returns 404.
  • channel is whatsapp, sms, email, or rcs. status is subscribed or unsubscribed.
  • whatsapp updates the person's WhatsApp opt-out. For sms and email, journey messages marked as marketing skip people who unsubscribed from that channel. See Contact policy.

Register a device for push

POST /customers/{id}/devices registers a Firebase Cloud Messaging token so the Send Push journey step can reach that phone.

curl -X POST https://api.usekontakt.com/v1/customers/3c9e2b14-0f6a-4d2b-8c71-5e9a0d3f1b28/devices \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "token": "fcm-registration-token", "platform": "ios" }'

Returns {"ok": true}. platform defaults to android. Send "unregistered": true with the same token when the user signs out or turns off notifications. See Push.

Troubleshooting

Events create duplicate people

Your calls use different identifiers for the same person, or emails in different cases. Send the same user_id on every call.

Anonymous events each create a new person

You're sending your own anonymous ID. Call POST /customers with no identity first, store the anonymous_id it returns, and send that.

A journey didn't start after an event

Check the event name matches the journey trigger exactly. A 202 response with "ignored": true means the key or event is switched off under Events / Sources.