REST API Documentation

Getting Started

Welcome to the Customer.io REST API.

You can send behavioral events to Customer.io from many different languages.

If you’re using a language not listed here, we’d be happy to help you integrate with our REST API or create a library that we can add to this area.

Javascript Snippet or Backend language?

The Javascript snippet tracks basic behavior for you just by copy/pasting it onto your site. In many cases, using the Javascript snippet will be easier to integrate with your app, but there are several reasons why sending events from your backend is useful:

You’re not planning on triggering emails based on how customers interact with your website (e.g. users who haven’t visited the site in X days)
You’re using the Javascript snippet, but have a few events you’d like to send from your backend system. They will work well together!
You’d rather not have another Javascript snippet slowing down your frontend. Our snippet is asynchronous (doesn’t affect initial page load) and very small, but we understand.

In the end, the decision on whether or not to send events from your backend or the Javascript snippet should be based on what works best for you. You’ll be able to integrate fully with Customer.io with either approach.

Supported Languages

Authentication

All requests to the Customer.io API must be authenticated via HTTP Basic Auth.

To authenticate, you provide your site id as the username, and your secret API key as the password. You can find these values in the integration area of your Customer.io account.

Nothing will work unless you include this API key

curl -i https://track.customer.io/auth \
 -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

var _cio = _cio || [];

(function() {
  var a,b,c;a=function(f){return function(){_cio.push([f].
  concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
  "sidentify","track","page"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
  var t = document.createElement('script'),
      s = document.getElementsByTagName('script')[0];
  t.async = true;
  t.id    = 'cio-tracker';
  t.setAttribute('data-site-id', 'YOUR SITE ID HERE');
  t.src = 'https://assets.customer.io/assets/track.js';
  s.parentNode.insertBefore(t, s);
})();

var cio = new CIO("YOUR SITE ID", "YOUR API SECRET KEY");

$customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY")

from customerio import CustomerIO
cio = CustomerIO("YOUR SITE ID", "YOUR API SECRET KEY")

import (
    // ...
    "github.com/customerio/go-customerio"
)

cio := customerio.NewCustomerIO("YOUR SITE ID", "YOUR API SECRET KEY")

Limits

The limits of our data collection API are listed inline with each endpoint’s documented parameters in addition to a broad overview here.

Identify Limits

Data Type	Limit	Description
Customer ID	150 bytes	Max length of customer ID value for Identify call
Customer Attribute Name	150 bytes	Max length of attribute names for Identify call
Customer Attribute Value	1000 bytes	Max length of attribute values for Identify call
Unique Identify attributes	30	Max number of attributes that can be included per Identify call

Event Limits

Data Type	Limit	Description
Event Name	100 bytes	Max length of event name for Track call
Event Data	10000 bytes	Max length of event data for Track call

Rate Limits

When sending data to Customer.io, API calls should be limited to 30 requests per second. This limit applies to both active data integrations, as well as historical backfill scripts.

If this rate limit is exceeded we will reach out to help you correct your integration. However we reserve the right to block your API calls if your integration is exceeding this limit in a way that degrades performance for our customers.

Errors

Customer.io uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Customer.io’s servers.

Code	Name	Description
200	OK	Everything worked as expected
400	Bad Request	Often missing a required parameter
401	Unauthorized	No valid API key provided
404	Not Found	The requested item does not exist
500, 502, 503, 504	Server errors	Something went wrong on our end

Introduction

Below we document the REST API endpoints and corresponding examples using some of our official libraries.

The REST API can be accessed at https://track.customer.io/ and displays a summary of every endpoint when navigated to directly.

We’ve documented the most commonly used endpoints in detail below to assist in getting started with your integration. The API documentation is focused around our REST API, but we will provide equivelent language implementation examples from our official libraries where possible.

Update Customer

https://track.customer.io/api/v1/customers/:id

Creating or updating customers via the REST API accomplishes the same goal as the identify method in the Javascript snippet. It allows you to pass attributes of your customers to us which you can then use to personalized your triggered emails or affect the logic of who receives them.

Parameters

id: The unique identifier for the customer - (required); Max length - 150 bytes
email: The email address of the user - (recommended); Max attribute value length - 1000 bytes
created_at: The UNIX timestamp from when the user was registered in your system - (recommended); Max attribute value length - 1000 bytes
attributes: Custom attributes to define the customer - (optional); Max attribute name length - 150 bytes; Max attribute value length - 1000 bytes

There is a limit of 30 unique attributes set per identify call

Updating or removing attributes

You can also update a customer’s attributes after creating them, using the same PUT API call. Don’t worry about sending only the attributes which have changed, our API takes care of that for you.

To remove an attribute on an existing customer, set its value to an empty string.

Response

A 200 response code signifies the customer was created or updated. All other response codes mean something went wrong. You can use the errors section above to diagnose the error.

curl -i https://track.customer.io/api/v1/customers/:id \
 -X PUT \
 -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
 -d email=customer@example.com \
 -d created_at=1361205308 \
 -d first_name=Bob \
 -d plan=basic

curl -i https://track.customer.io/api/v1/customers/:id \
 -X PUT \
 -H "Content-Type: application/json" \
 -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
 -d '{"email":"customer@example.com","created_at":1361205308,"first_name":"Bob","plan":"basic"}'

_cio.identify({
  id: 5,
  email: 'customer@example.com',
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
});

cio.identify(5, {
  email: 'customer@example.com',
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
});

$customerio.identify(
  id: 5,
  email: "customer@example.com",
  created_at: 1361205308,
  first_name: "Bob",
  plan: "basic"
)

cio.identify(id=5, email='customer@example.com', created_at=1361205308, first_name='Bob', plan='basic')

cio.Identify("5", map[string]interface{}{
  "email": "customer@example.com",
  "created_at": time.Now().Unix(),
  "first_name": "Bob",
  "plan": "basic",
})

Delete Customer

https://track.customer.io/api/v1/customers/:id

Parameters

id: The unique identifier for the customer - (required); Max length - 150 bytes

Deleting a customer will remove them, and all their information from Customer.io.

Note: if you’re still sending data to Customer.io via other means (such as the Javascript snippet), the customer could be recreated.

This action is not available with the Javascript snippet alone

Response

A 200 response code signifies the customer was deleted. All other response codes mean something went wrong. You can use the errors section above to diagnose the error.

curl -i https://track.customer.io/api/v1/customers/:id \
 -X DELETE \
 -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

cio.destroy(5);

$customerio.delete(5)

cio.delete(customer_id=5)

cio.Delete("5")

Customer Events

https://track.customer.io/api/v1/customers/:id/events

To send an event to Customer.io outside of the browser, say from your server side code, you can POST to the events resource for a given customer.

Parameters

id: The unique identifier for the customer - (required); Max length - 150 bytes
name: The name of the event to track - (required); Max length - 100 bytes
data: Custom data to include with the event - (optional); Max event data length - 10000 bytes

Response

A 200 response code signifies the event was successfully tracked. All other response codes mean something went wrong. You can use the errors section above to diagnose the error.

When using the Javascript snippet to track events you must call the track API call after previously identifying the user or else the event will not associate to the user’s profile.

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d name=purchase \
  -d data[price]=23.45 \
  -d data[product]=socks

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"name":"purchase","data":{"price": "23.45", "product": "socks"}}'

_cio.track("purchase", { price: "23.45", product: "socks" });

cio.track(5, {
  name: 'purchase',
  data: {
    price: "23.45",
    product: "socks"
  }
});

$customerio.track(5, "purchase", price: "23.45", product: "socks")

cio.track(customer_id=5, name="purchase", price="23.45", product="socks")

cio.Track("5", "purchase", map[string]interface{}{
  "price": "23.45",
  "product": "socks",
})

Anonymous Events

https://track.customer.io/api/v1/events

Anonymous events can also be sent to Customer.io by way of a POST to the events resource directly without a customer ID.

Parameters

name: The name of the event to track - (required); Max length - 100 bytes
data: Custom data to include with the event - (optional); Max event data length - 10000 bytes

Response

A 200 response code signifies the event was successfully tracked. All other response codes mean something went wrong. You can use the errors section above to diagnose the error.

Use case

You can use anonymous events to send invitation emails to people not yet in your Customer.io database.

curl -i https://track.customer.io/api/v1/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d name=purchase \
  -d data[recipient]=customer@example.com \
  -d data[price]=23.45 \
  -d data[product]=socks

curl -i https://track.customer.io/api/v1/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"name":"purchase","data":{"recipient":"customer@example.com", "price": "23.45", "product": "socks"}}'

$customerio.anonymous_track("purchase", recipient: "customer@example.com", price: "23.45", product: "socks")

Page View Events

https://track.customer.io/api/v1/customers/:id/events

To send a page view event to Customer.io directly from the REST API, you can POST to the events resource for a given customer and set the type to page.

Parameters

id: The unique identifier for the customer - (required); Max length - 150 bytes
name: The name of the page to track - (required); Max length - 100 bytes
type: Sets the event type. Must be set to “page” - (required); Max length included in 10000 byte event data limit
data: Custom data to include with the page view - (optional); Max event data length - 10000 bytes

Response

A 200 response code signifies the event was successfully tracked. All other response codes mean something went wrong. You can use the errors section above to diagnose the error.

The Javascript snippet automatically sends these events based on when any page that includes it is loaded.

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d name=http://google.com/search \
  -d type=page \
  -d data[referrer]=http://google.com

curl -i https://track.customer.io/api/v1/customers/:id/events \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"name":"http://google.com/search", "type": "page", "data":{"referrer": "http://google.com"}}'

_cio.page("https://example.com/landing", {property: "value", additional: "value"})
// Note: _cio.page() calls must occur after the user has already been identified via _cio.identify().
// Custom data attributes are optional.

cio.trackPageView(5, "http://google.com/search");

$customerio.track(5, "http://google.com/search", type: "page", referrer: "http://google.com")

cio.track(customer_id=5, name="http://google.com/search", type="page", referrer="http://google.com")

cio.Track("5", "http://google.com/search", map[string]interface{}{
  "type": "page",
  "referrer": "http://google.com"
})