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 to | Endpoint |
|---|---|
| Create or update a person's profile | POST /customers |
| Record something a person did, and start journeys | POST /events |
| Capture a form submission or sign-up lead | POST /leads |
| Merge an anonymous visitor into a known person | POST /identify |
| Record an order from a store Kontakt isn't connected to | POST /orders |
| Record a subscribe or unsubscribe for a channel | POST /consent |
| Register a phone for push notifications | POST /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:
customer_id: the Kontakt ID returned by earlier calls.user_id: your own ID for the person. Kontakt stores it and shows it as the person's user ID.email: an exact match, so send emails in one consistent format, such as lowercase.phone: E.164, such as+2348030000000, is best.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, orphoneis saved only when the person doesn't have one yet. - Tags.
tags(oradd_tags) adds tags andremove_tagsremoves 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 includestagswith the person's full list. - Consent. Each
consententry needs achannel(whatsapp,sms,email, orrcs) and astatus(subscribed,unsubscribed, orunknown). - Anonymous visitors. Send no identity at all and Kontakt creates an anonymous person and returns an
anonymous_idstarting withanon_. Store it in your app and send it with later events and withPOST /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"]
}
| Field | Required | Notes |
|---|---|---|
event | Yes | The event name journeys trigger on |
customer_id, user_id, email, phone, or anonymous_id | At least one | See How Kontakt finds the person |
properties | No | Event details, available to journey conditions and messages |
traits | No | Profile updates, using the same keys as customer properties. Empty strings are ignored. whatsapp_opt_in: false opts the person out of WhatsApp marketing. |
timestamp | No | When it happened. Defaults to now. |
tags, remove_tags | No | Tags to add or remove, as an array or comma-separated string. add_tags also works. The response then includes tags. |
idempotency_key | No | A 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_customer | No | Default 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.
nameis split into first and last name. fieldsare merged into custom fields.form_idandform_nameare saved as custom fields too.attributionacceptssource,medium,campaign,content,term,ad_id, andlanding_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, orsubmission, reads field arrays with labels and values, finds email and phone fields by their labels, and picks up hidden UTM fields such asutm_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_mergedsays how many events moved. - Otherwise the anonymous record becomes the known person.
- Send
referred_by_codewith a referral code to credit the referrer. See Referrals. - An unknown
anonymous_idreturns404. Onlyanonymous_idvalues 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, andtotal.store_idis your own name for the store; Kontakt creates the store the first time it sees it. - Retries and updates. Orders are matched on
store_idandorder_id. Send the same order again with a newfinancial_statusorfulfillment_statusto update it. - Events. A new order records
commerce.order_placed. Changingfinancial_statustopaidrecordscommerce.order_paid. Changingfulfillment_statustofulfilledrecordscommerce.order_fulfilled. - Linking the person. Send
email,phone, orexternal_customer_id. Without any of them the order is stored but not linked to anyone, and no events are recorded. - Test orders. Set
"test": trueto 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.
Consent
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, orphone. Consent never creates a person; an unknown person returns404. channeliswhatsapp,sms,email, orrcs.statusissubscribedorunsubscribed.whatsappupdates the person's WhatsApp opt-out. Forsmsandemail, 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.