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

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

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.