RESTful API

Summary

When you need a bit more control, you can create/update customers and track custom events through out RESTful API. This is a currently a write-only API.

Authentication

All requests to the Customer.io API must be authenticated via HTTP Basic Auth. Also, HTTPS must be used for all API requests. Any attempts to use HTTP will result in failure.

To authenticate, you provide your same site id used in the javascript snippet above as the username, and your secret API key as the password. You can find these values in the tracking area.

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.

Creating or updating customers

Creating or updating customers via the API accomplishes the same goal as the identify method in the javascript API. 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.

Arguments

• CUSTOMER_ID (required) – a unique identifier for the customer. This should be the same id you’d pass into the Javascript API identify command above.

POST data

• email (required) – the email address of the user.
• other attributes (optional) – you can pass any other attributes to us which would be useful in your triggers.

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.

Deleting customers

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.

Arguments

• CUSTOMER_ID (required) – a unique identifier for the customer. This should be the same id you’d pass into the Javascript API identify command.

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.

Track a custom event

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.

Arguments

• CUSTOMER_ID (required) – a unique identifier for the customer. This should be the same id you’d pass into the Javascript API identify command above.

POST data

• name (required) – the name of the event you want to track.
• data (optional) – any related information you’d like to attach to this event. These attributes can be used in your triggers to control who should receive the triggered email. You can set any number of data key and values.

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.