Full HTTP API Reference

This REST API allows you to identify people, add or remove people from segments, and track events from your own websites or web applications. If you want to check our API libraries click here

Here is what we will cover:

API endpoint
Authentication
Format
Response codes
HTTP POST - Identify people and add or remove them from segments
HTTP POST - Track events

API Endpoint

Access to all the resources available via API is over HTTPS and from the host:

https://api.convertloop.co/v1/

The API Endpoint to identify people and add or remove people from segments is:

https://api.convertloop.co/v1/people

The API Endpoint to track events is:

https://api.convertloop.co/v1/event_logs

Authentication

REST API requests will require a Basic Authentication with your app_id and api_key, which you can find in Settings -> Account once you are logged in.

Format

We use JSON to send and receive information.

Response codes

Code	Name	Description
200	OK	General success status code. The request is successful and its information is inlcuded in the HTTP/S response
400	Bad Request	General error for when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.
401	Unathorized	Error code response for missing or invalid authentication token
404	Not Found	Used when the requested resource is not found
422	Unprocessable Entity	The server is unable to process the request with the given information.
500	Server Error	Internal server error. Please try again later.

HTTP POST - Identify people and add or remove people from segments

This endpoint is used for both identifying people and adding or removing people from segments. You need to do an HTTP POST to the following URL:

https://api.convertloop.co/v1/people

You can use the following keys in the JSON you send to the URL (any other key will be treated as a custom attribute of the contact):

Attribute	Description	Value data type
`pid`	This is the unique cookie value for each contact. You can obtain this value from the cookie `dp_pid`	string Required if `email` or `user_id` is not present.
`user_id`	This is the the id of a specific user in your application. You can use it to match the user in your application with the `contact` in ConvertLoop when the person you want to identify is logged into your site.	string Required if `pid` or `email` is not present
`email`	This is the attribute to assign an email value to a specific `person`.	string Required if `pid` or `user_id` is not present
`add_to_segments`	This is the attribute to add a `contact` to one or several segments. Learn how	string Optional
`remove_from_segments`	This is the attribute to remove a `contact` from one or several segments. Learn how	string Optional
`first_seen_at`	This is the first date and time a `person` has visited your App. This info is sent by default to ConvertLoop if you have installed your tracking code.Learn how to install it	datetime Optional
`last_seen_at`	This is the last date and time a `person` has visited your App. This info is sent by default to ConvertLoop if you have installed your tracking code.Learn how to install it.	datetime Optional
`resubscribe`	This attribute allows you to automatically resubscribe a `person`that have previously unsubscribe from your contacts by passing the attribute`resubscribe: true`	boolean Optional

Checkout the sections Identifying a person and Adding people to a segment to see examples using different programming languages.

HTTP POST - Track an event

To track an event you need to do an HTTP POST to the following URL:

https://api.convertloop.co/v1/event_logs

You can use the following keys in the JSON you send to the URL:

Attribute	Description	Data type
`name`	This is the attribute to assign a name to a custom `event_log`	string required
`occured_at`	This is the date and time at which the `event_log` has occurred. If you don't specify the `ocurred_at` key, the current time will be used	datetime optional
`person`	You can use the `person` key to add custom attributes to any specific `person` or to add or remove people from segments, by passing `{key:value}` pairs to the `person` key. Learn how	hash optional if not creating or updating a `contact`
`metadata`	You can use the `metadata` key to add attributes related to the event you are logging, by passing `{key:value}` pairs to the `metadata` key. Learn how	hash optional

Checkout the section Tracking an event to see an example using different programming languages.