REST API
The Contlo REST API lets your backend do what the tracking snippet and mobile SDKs do from the client: create or update a contact, and record an event against them. Use it for things that happen away from the browser, such as an order confirmed in your own checkout, a subscription renewal or a point-of-sale purchase, so those moments can trigger automations and count toward revenue.
Las guías están en inglés.
Endpoints at a glance
There are two versions. Both take the same key and the same core fields. Pick one and use it for both identify and track.
| Version | Endpoint | Use it when |
|---|---|---|
| v1 | POST https://marketing.contlo.com/v1/identify | You want the contact created or updated before the response returns. |
| v1 | POST https://marketing.contlo.com/v1/track | You send events that are already set up for your account and want property types checked on the way in. |
| v1 | GET https://marketing.contlo.com/v1/shop_api_details | You want to check that a key is valid. |
| v2 | POST https://api1.contlo.com/v2/identify | You send high volumes and are happy for the contact to be processed after the response. This is what the mobile SDKs call. |
| v2 | POST https://api1.contlo.com/v2/track | You send high volumes of events. This is what the mobile SDKs call. |
Authentication
Every request carries your API key in the X-API-KEY header. Send and accept JSON.
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: application/jsonFind your keys under Settings → Marketing Settings → API Keys.
| Key | Where to use it |
|---|---|
| Public API Key | Front-end code. It is the key inside your tracking snippet and is safe to expose. The identify and track endpoints accept it. |
| Private API Keys | Server-side code only. Click Create API Key, give it a name and copy it. Create one key per system so you can delete one without breaking the others. |
For more on creating, renaming and deleting keys, see API keys and webhooks.
Check a key
curl https://marketing.contlo.com/v1/shop_api_details \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"{
"success": true,
"shop_id": 12345,
"api_throttling_limit": 600,
"platform": "CUSTOM"
}An unknown key returns "success": false with an error message. api_throttling_limit is your account's request limit per minute.
Identify a contact (v1)
Creates the contact if it does not exist, or updates it if it does. Contacts are matched by email first, then by phone number.
curl -X POST https://marketing.contlo.com/v1/identify \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "ada@example.com",
"phone_number": "+14155550123",
"first_name": "Ada",
"last_name": "Lovelace",
"city": "San Francisco",
"province": "California",
"country": "United States",
"zip": "94107",
"custom_properties": {
"loyalty_tier": "gold",
"preferred_category": "running"
}
}'{
"success": true,
"external_id": "CONTACT_EXTERNAL_ID"
}| Field | Type | Notes |
|---|---|---|
email | string | Required unless phone_number is sent. |
phone_number | string | Required unless email is sent. Include the plus sign and country code. Must contain 9 to 13 digits. |
first_name, last_name | string | Optional. |
city, province, country, zip | string | Optional. |
custom_properties | object | Optional. Each key becomes a contact property. See Custom properties and tags. |
external_id in the response is Contlo's ID for the contact. Store it if you want to reference the contact later with external_profile_id in a track call.
Track an event (v1)
curl -X POST https://marketing.contlo.com/v1/track \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event": "subscription_renewed",
"email": "ada@example.com",
"properties": {
"plan": "annual",
"amount": 199.0,
"renewal_date": "2026-11-20"
},
"profile_properties": {
"subscription_status": "active"
}
}'{
"success": true,
"external_id": "CONTACT_EXTERNAL_ID"
}| Field | Type | Notes |
|---|---|---|
event | string | Required. The key of an event that is set up for your account. |
email, phone_number | string | Identify the contact. If no contact matches, one is created. |
customer_id | string | The contact's customer ID in your store. An alternative way to identify them. |
external_profile_id | string | The external_id Contlo returned for the contact. An alternative way to identify them. |
properties | object | Details of this event. |
profile_properties | object | Optional. Contact properties to set at the same time. |
skip_new_profile_creation | boolean | Optional. Send true to record the event only if the contact already exists. If it does not, the response is 200 with "success": false and "error": "Profile not found". |
Send at least one of email, phone_number, customer_id or external_profile_id.
Events must be set up first
The v1 track endpoint accepts only events your account already knows, each with a list of properties and their types. Properties that are not on that list are dropped, and a property with the wrong type rejects the request. To have a new event set up, write to hello@contlo.com with the event key and its properties.
| Property type | Accepted value |
|---|---|
| string | Any text. |
| number | An integer or decimal, such as 199 or 199.50. |
| boolean | true or false. |
| date | A date containing YYYY-MM-DD. |
| datetime | Any timestamp that can be parsed, such as 2026-11-20T10:30:00Z. |
| An email address. | |
| phone_number | A phone number with 9 to 13 digits. |
| url | An http or https URL. |
| array | A JSON array. |
Subscribe a contact with an event
To record consent along with an event, include subscribed_channels inside profile_properties, listing any of EMAIL, SMS and WHATSAPP.
"profile_properties": {
"subscribed_channels": ["EMAIL", "WHATSAPP"]
}Identify and track (v2)
The v2 endpoints accept the request, answer with 202 Accepted and process it in the background. They do not require an event to be set up in advance: a new event and its properties are registered from the first request that carries them. Keep each property's type the same from then on. A property that later arrives with a different type is stored as a separate property.
curl -X POST https://api1.contlo.com/v2/identify \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "ada@example.com",
"phone_number": "+14155550123",
"first_name": "Ada",
"last_name": "Lovelace",
"city": "San Francisco",
"country": "United States",
"zip": "94107",
"custom_properties": { "loyalty_tier": "gold" },
"is_profile_update": false
}'{
"success": true,
"error": null,
"external_id": null
}curl -X POST https://api1.contlo.com/v2/track \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event": "subscription_renewed",
"email": "ada@example.com",
"device_event_time": 1795170600000,
"properties": {
"plan": "annual",
"amount": 199.0
},
"profile_properties": {
"subscription_status": "active"
}
}'{
"success": true,
"error": null,
"external_id": "CONTACT_EXTERNAL_ID"
}| Field | Endpoint | Notes |
|---|---|---|
email | Both | Must be a valid email address. |
phone_number | Both | Include the plus sign and country code. A number sent without a plus sign is treated as an Indian number. |
fcm_token, apns_token | Both | The device's push token, for Android and iOS. Used by the mobile SDKs. |
external_id | Both | Contlo's ID for the contact, if you have it. |
first_name, last_name, city, country, zip | Identify | Optional contact details. |
custom_properties | Identify | Contact properties to set. |
is_profile_update | Identify | Marks the call as an update to an existing contact. |
mobile_push_consent, web_push_consent | Both | Boolean. Whether the contact has allowed push on this device or browser. |
event | Track | Required. |
properties | Track | Required. Must be an object, and no value in it may be null. Send {} if you have nothing to add. |
profile_properties | Track | Optional. Contact properties to set at the same time. |
device_event_time | Track | Optional. When the event happened, as a Unix timestamp in milliseconds. A value in seconds is also accepted. Defaults to the time the request arrives. |
event_id | Track | Optional. A numeric ID you generate for the event. |
session_id | Track | Optional. An ID that groups events from one visit. |
A track request needs at least one of email, phone_number, fcm_token or apns_token.
Rate limits
- The v1 endpoints share one limit per account, counted per minute. The default is 600 requests per minute. Your current value is returned as
api_throttling_limitby the key check call. - When you go over the limit,
/v1/trackanswers429withThrottling Limit Reached: Please connect for increase in Rate Limit, and/v1/identifyanswers502with an empty body. Wait for the next minute and retry. - If you need a higher limit, ask your account manager or write to hello@contlo.com.
- Send requests one contact or one event at a time. There is no batch endpoint.
Errors
Failed requests return "success": false, usually with an error message.
| Status | Error | What to do |
|---|---|---|
401 | No message | The X-API-KEY header is missing or the key is not recognized. |
400 | Invalid email or phone number or device token | v1 identify: send an email or a phone_number. |
400 | Invalid email format | v1 identify: fix the email address. |
400 | Invalid phone format | v1 identify: the phone number must contain 9 to 13 digits. |
400 | Invalid email or phone number or fcm_token | v1 track: the request did not identify a contact. |
400 | Please whitelist the schema before sending events.. | v1 track: the event is not set up for your account. See Events must be set up first. |
400 | Invalid key value for <property> as per schema. Please contact your developer!! | v1 track: the named property has the wrong type. |
500 | Failed to create or find profile | v1 track: the contact could not be created. Retry, and check the email and phone values. |
400 | At least one of the customer identifiers must be provided. | v2 track: send an email, phone_number or device token. |
400 | Event is required. | v2 track: add the event field. |
400 | The 'properties' field cannot be null. | v2 track: add a properties object, even an empty one. |
400 | The 'properties' field cannot have null values. | v2 track: remove keys whose value is null. |
400 | The phone number is incorrect. | v2 track: send a valid number with the plus sign and country code. |
500 | Internal Server Error | v2 track: the event could not be processed. Retry after a short wait. |
Good practice
- Keep private keys on your server. If a key leaks, delete it under API Keys and create a new one.
- Always send phone numbers with the plus sign and country code, so the contact is matched in the right country.
- Use the same event names and property keys across web, app and server. See naming advice.
- Retry on
429and5xxwith a growing delay. Do not retry400or401without changing the request. - After your first calls, look the contact up under Audience to confirm the properties arrived, then check that the event is available in a segment condition. See Contacts and Segments.
Guías relacionadas
- API keys, webhooks and callback URLsFind your public API key, create and revoke private API keys, and learn where webhooks and callback URLs live in Contlo.
- Track events and identify visitorsUse the Contlo browser methods to tell Contlo who a visitor is and what they did, then use those events in segments, automations and analytics.
- Mobile SDKsAdd Contlo to an Android, iOS, React Native or Expo app: install, initialize, identify users, track events and set up push notifications.
- Install web trackingAdd the Contlo tracking snippet to a custom site, see what it records automatically, verify the install and review the cookies it sets.
- Custom properties and tagsAdd your own contact properties to store details Contlo doesn't track by default, and manage the tags you use to organize campaigns.