Saltar al contenido
Contlo by QuestionPro
Explorar la documentación

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.

Settings → Marketing Settings → API KeysJSON over HTTPSAPI key in a headerIdentify and track

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.

VersionEndpointUse it when
v1POST https://marketing.contlo.com/v1/identifyYou want the contact created or updated before the response returns.
v1POST https://marketing.contlo.com/v1/trackYou send events that are already set up for your account and want property types checked on the way in.
v1GET https://marketing.contlo.com/v1/shop_api_detailsYou want to check that a key is valid.
v2POST https://api1.contlo.com/v2/identifyYou send high volumes and are happy for the contact to be processed after the response. This is what the mobile SDKs call.
v2POST https://api1.contlo.com/v2/trackYou 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.

Headers
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Find your keys under Settings → Marketing Settings → API Keys.

KeyWhere to use it
Public API KeyFront-end code. It is the key inside your tracking snippet and is safe to expose. The identify and track endpoints accept it.
Private API KeysServer-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

Request
curl https://marketing.contlo.com/v1/shop_api_details \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"
Response: valid key
{
  "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.

Request
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"
    }
  }'
Response: 200
{
  "success": true,
  "external_id": "CONTACT_EXTERNAL_ID"
}
FieldTypeNotes
emailstringRequired unless phone_number is sent.
phone_numberstringRequired unless email is sent. Include the plus sign and country code. Must contain 9 to 13 digits.
first_name, last_namestringOptional.
city, province, country, zipstringOptional.
custom_propertiesobjectOptional. 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)

Request
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"
    }
  }'
Response: 200
{
  "success": true,
  "external_id": "CONTACT_EXTERNAL_ID"
}
FieldTypeNotes
eventstringRequired. The key of an event that is set up for your account.
email, phone_numberstringIdentify the contact. If no contact matches, one is created.
customer_idstringThe contact's customer ID in your store. An alternative way to identify them.
external_profile_idstringThe external_id Contlo returned for the contact. An alternative way to identify them.
propertiesobjectDetails of this event.
profile_propertiesobjectOptional. Contact properties to set at the same time.
skip_new_profile_creationbooleanOptional. 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 typeAccepted value
stringAny text.
numberAn integer or decimal, such as 199 or 199.50.
booleantrue or false.
dateA date containing YYYY-MM-DD.
datetimeAny timestamp that can be parsed, such as 2026-11-20T10:30:00Z.
emailAn email address.
phone_numberA phone number with 9 to 13 digits.
urlAn http or https URL.
arrayA 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.

Example
"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.

Identify request
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
  }'
Identify response: 202
{
  "success": true,
  "error": null,
  "external_id": null
}
Track request
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"
    }
  }'
Track response: 202
{
  "success": true,
  "error": null,
  "external_id": "CONTACT_EXTERNAL_ID"
}
FieldEndpointNotes
emailBothMust be a valid email address.
phone_numberBothInclude the plus sign and country code. A number sent without a plus sign is treated as an Indian number.
fcm_token, apns_tokenBothThe device's push token, for Android and iOS. Used by the mobile SDKs.
external_idBothContlo's ID for the contact, if you have it.
first_name, last_name, city, country, zipIdentifyOptional contact details.
custom_propertiesIdentifyContact properties to set.
is_profile_updateIdentifyMarks the call as an update to an existing contact.
mobile_push_consent, web_push_consentBothBoolean. Whether the contact has allowed push on this device or browser.
eventTrackRequired.
propertiesTrackRequired. Must be an object, and no value in it may be null. Send {} if you have nothing to add.
profile_propertiesTrackOptional. Contact properties to set at the same time.
device_event_timeTrackOptional. 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_idTrackOptional. A numeric ID you generate for the event.
session_idTrackOptional. 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_limit by the key check call.
  • When you go over the limit, /v1/track answers 429 with Throttling Limit Reached: Please connect for increase in Rate Limit, and /v1/identify answers 502 with 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.

StatusErrorWhat to do
401No messageThe X-API-KEY header is missing or the key is not recognized.
400Invalid email or phone number or device tokenv1 identify: send an email or a phone_number.
400Invalid email formatv1 identify: fix the email address.
400Invalid phone formatv1 identify: the phone number must contain 9 to 13 digits.
400Invalid email or phone number or fcm_tokenv1 track: the request did not identify a contact.
400Please whitelist the schema before sending events..v1 track: the event is not set up for your account. See Events must be set up first.
400Invalid key value for <property> as per schema. Please contact your developer!!v1 track: the named property has the wrong type.
500Failed to create or find profilev1 track: the contact could not be created. Retry, and check the email and phone values.
400At least one of the customer identifiers must be provided.v2 track: send an email, phone_number or device token.
400Event is required.v2 track: add the event field.
400The 'properties' field cannot be null.v2 track: add a properties object, even an empty one.
400The 'properties' field cannot have null values.v2 track: remove keys whose value is null.
400The phone number is incorrect.v2 track: send a valid number with the plus sign and country code.
500Internal Server Errorv2 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 429 and 5xx with a growing delay. Do not retry 400 or 401 without 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

¿No encuentras algo? Escríbenos