Getting Started

Welcome to the Customer.io 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 API or create a library that we can add to this area.

Behavioral Tracking vs. API

There are two primary API hosts available for you to integrate with:

Behavioral Tracking

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

Our Behavioral Tracking API is used to identify and track customer data with Customer.io.

API

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

Our API allows you to read data from your Customer.io account for use in custom workflows in your backend system or for reporting purposes.

JS 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

• Javascript in browser
• Node.js
• Ruby
• Python
• Go
• PHP
• 3rd party libraries like c#, scala and others

Authentication

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")

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

Limits

Identify Limits

Event Limits

API Triggered Broadcast Limits

Rate Limits

When sending data to Customer.io, Behavioral Tracking 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 search failed, etc.), and codes in the 5xx range indicate an error with Customer.io’s servers.

Behavioral Tracking

Introduction

API Host: https://track.customer.io/api/v1

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

The Behavioral Tracking API meta info 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 the REST HTTP API, but we will provide equivelent language implementation examples from our official libraries where possible.

/customers/:id

API Host: https://track.customer.io/api/v1

Create or update a customer

Parameters

id

The unique identifier for the customer

email

The email address of the user

created_at

The UNIX timestamp from when the user was created in your system

attributes

Custom attributes to define the customer

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",
})

Creating or updating customers via the Behavioral Tracking 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.

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.

/customers/:id

API Host: https://track.customer.io/api/v1

Delete a customer

Parameters

id

The unique identifier for the customer

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")

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

/customers/:id/devices

API Host: https://track.customer.io/api/v1

Create or update a customer device

Parameters

id

The unique identifier for the customer

device_id

The unique token for the user device

platform

The platform for the user device. Allowed values are 'ios' and 'android'.

last_used

UNIX timestamp representing the last used time for the device. If this is not included we default to the time of the device identify.

curl -i https://track.customer.io/api/v1/customers/:id/devices \
  -X PUT \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d device[id]=my_ios_device_id \
  -d device[platform]=ios \
  -d device[last_used]=1514764800

curl -i https://track.customer.io/api/v1/customers/:id/devices \
  -X PUT \
  -H "Content-Type: application/json" \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -d '{"device":{"id": "my_android_device_id", "platform": "android", "last_used": 1514764800}}'

// Add iOS device
cio.addDevice(1, "my_ios_device_id", "ios");
// Add android device
cio.addDevice(1, "my_android_device_id", "android");

// Add device with custom "last_used" value
cio.addDevice(1, "my_ios_device_id", "ios", {"last_used": 1514764800});

# Add iOS device
$customerio.add_device(5, "my_ios_device_id", "ios")
# Add Android device
$customerio.add_device(5, "my_android_device_id", "android")

# Add device with custom "last_used" value
$customerio.add_device(5, "my_ios_device_id", "ios", {:last_used=>1514764800})

# Add iOS device
cio.add_device(customer_id=1, device_id='my_ios_device_id', platform='ios')
# Add Android device
cio.add_device(customer_id=1, device_id='my_android_device_id', platform='android')

# Add device with custom "last_used" value
cio.add_device(customer_id=1, device_id='my_ios_device_id', platform='ios', last_used=1514764800)

// Add iOS device
cio.AddDevice("5", "my_ios_device_id", "ios", nil)
// Add Android device
cio.AddDevice("5", "my_android_device_id", "android", nil)

// Add device with custom "last_used" value
cio.AddDevice("5", "my_ios_device_id", "ios", map[string]interface{}{
  "last_used": 1514764800,
})

To identify mobile devices for use in Push messaging you need to form a PUT call to the devices endpoint for a given customer.

/customers/:id/devices

API Host: https://track.customer.io/api/v1

Delete a customer device

Parameters

id

The unique identifier for the customer

device_id

The unique token for the user device

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

cio.deleteDevice(1, "my_device_id");

$customerio.delete_device(5, "my_device_id")

cio.delete_device(customer_id=1, device_id='my_device_id')

cio.DeleteDevice("5", "my_device_id")

Deleting a mobile device will remove the device from a customer’s profile in Customer.io.

Note: if you’re still sending data about the device to Customer.io via your integration the device will be recreated.

/customers/:id/suppress

API Host: https://track.customer.io/api/v1

Suppress a customer

Parameters

id

The unique identifier for the customer

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

To suppress a profile id in Customer.io from your server side code, you can POST to the suppress resource for a given profile ID. If we receive further API event/identify calls for the same profile ID, we’ll notice the id is suppressed and ignore the received API calls.

In addition to suppressing the profile ID we will also delete the user profile from Customer.io the same way we would when calling the identify endpoint with the DELETE method.

WARNING: This API call will NOT add anyone’s email address to the global suppression list for your account. Instead, it will delete the user’s profile AND cause us to ignore future API calls that attempt to create a new profile with the same profile id. If you need to suppress deliveries for a particular email address, please reach out to our support team or your email admin.

/customers/:id/unsuppress

API Host: https://track.customer.io/api/v1

Unsuppress a customer

Parameters

id

The unique identifier for the customer

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

If you need to resume tracking a previously suppressed profile ID in Customer.io you can POST to the unsuppress resource for a previously suppressed profile ID.

Following a call to unsuppress, identifies and events for a person will behave exactly as they would for a customer that we haven’t seen before. Identifying a person following an unsuppress will create an entirely new profile for them, with none of the history (messages, journeys, etc.) that might have existed for that ID prior to a suppress call.

WARNING: This API call will NOT remove anyone’s email address from the global suppression list for your account. Instead, it will reverse the effects of a SUPPRESS call (above) and cause us to allow future API calls that will create a new profile that uses a previously suppressed profile id. If you need to unsuppress deliveries for a particular email address, please reach out to our support team or your email admin.

/customers/:id/events

API Host: https://track.customer.io/api/v1

Track a customer event

Parameters

id

The unique identifier for the customer

name

The name of the event to track

type

Used to change event type. For Page View events set to "page".

data

Custom data to include with the event

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"}}'

// identify customer before tracking event
_cio.identify({id: 5});

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

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

// track page view event
cio.trackPageView(5, "http://google.com/search");

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

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

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

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

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

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

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.

Reserved Custom Data Parameters

There are a few important values which, if sent with the events that trigger campaigns, will override those campaign settings. These are:

1. Attachments
2. from_address
3. recipient
4. reply_to

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

/events

API Host: https://track.customer.io/api/v1

Track an anonymous event

Parameters

name

The name of the event to track

data

Custom data to include with the event

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"}}'

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

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

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

Reserved Custom Data Parameters

There are a few important values which, if sent with the events that trigger campaigns, will override those campaign settings. These are:

1. recipient
2. from_address
3. reply_to

The recipient event attribute is required if the anonymous event is used to trigger an email campaign.

Use case

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

/segments/:id/add_customers

API Host: https://track.customer.io/api/v1

Add people to a manual segment

Parameters

id

The unique identifier of the segment

ids

A list of customer ids to add to the segment

curl -i https://track.customer.io/api/v1/segments/:id/add_customers \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"ids":["customer_id1","customer_id2"]}'

cio.add_to_segment(segment_id=1,customer_ids=['customer_id1','customer_id2'])

cio.AddCustomersToSegment(1, []string["customer_id1","customer_id2"])

Manual segments are segments that you control by sending requests to our Behavioral Tracking API or by uploading lists of customers in the Customer.io application. You can add people to a segment by sending an add_customers request, and remove them by sending a remove_customers request.

There is a limit of 1000 customer ids per request

If you send customer ids that don’t exist yet in an add_customers request, we will automatically create customer profiles for the new customer ids.

NOTE: This API call is for use with manual segments only. It will NOT add anyone to data-driven segments. Please visit our documentation on segments to learn more about these segment types.

/segments/:id/remove_customers

API Host: https://track.customer.io/api/v1

Remove people from a manual segment

Parameters

id

The unique identifier of the segment

ids

A list of customer ids to remove from the segment

curl -i https://track.customer.io/api/v1/segments/:id/remove_customers \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"ids":["customer_id1","customer_id2"]}'

cio.remove_from_segment(segment_id=1,customer_ids=['customer_id1','customer_id2'])

cio.RemoveCustomersFromSegment(1, []string["customer_id1","customer_id2"])

There is a limit of 1000 customer ids per request

NOTE: This API call is for use with manual segments only. It will NOT remove anyone from data-driven segments. Please visit our documentation on segments to learn more about these segment types.

API

Introduction

API Host: https://api.customer.io/v1/api

Below we’ve documented our API which allows you to read data from your Customer.io account and trigger campaigns.

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 the REST HTTP API, but we will provide equivelent language implementation examples from our official libraries where possible.

/campaigns/:id/triggers

API Host: https://api.customer.io/v1/api

Trigger broadcast campaign

Parameters

id

The unique identifier for the campaign

data

Custom Liquid merge data to include with the trigger

recipients

Additional recipient conditions to filter recipients. If this is used, none of ids, emails, per_user_data, or data_file_url may be used.

ids

List of profile ids to use as campaign recipients. If this is used, none of recipients, emails, per_user_data, or data_file_url may be used.

id_ignore_missing

If false (the default) a missing id is an error.

emails

List of email addresses which are mapped to customer.io profiles and used as campaign recipients.

email_ignore_missing

If false (the default) a missing email address is an error.

email_add_duplicates

If false (the default) an email address associated with more than one profile id is an error.

per_user_data

an array of up to 10K json maps containing either "id" and "data" keys or "email" and "data" keys. If this is used, none of recipients, ids, emails, or data_file_url may be used.

data_file_url

a url from which we will retrieve a data file containing per-user data, each line containing a json map with either "id" and "data" or "email" and "data" keys. If this is used, none of recipeints, ids, emails, or per_user_data may be used.

curl -i https://api.customer.io/v1/api/campaigns/:id/triggers \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"data":{"headline":"Roadrunner spotted in Albuquerque!","date":1511315635, "text": "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"},"recipients":{"segment":{"id":7}}}'

cio.triggerBroadcast(5, {
  headline: "Roadrunner spotted in Albuquerque!",
  date: 1511315635,
  text: "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
}, { segment: { id: 7 }});

To send an API triggered broadcast in Customer.io from your server side code, you can POST to the triggers resource for a given campaign. The trigger id is returned if the broadcast has been successfully queued for processing.

/campaigns/:campaign_id/triggers/:trigger_id

API Host: https://api.customer.io/v1/api

Retrieve status of a broadcast

Parameters

campaign_id

The unique identifier for the campaign

trigger_id

Custom Liquid merge data to include with the trigger

curl -i https://api.customer.io/v1/api/campaigns/:id/triggers/:trigger_id -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE 

After triggering a broadcast you can retrive the status of that broadcast using a GET of the trigger_id resource.

/campaigns/:campaign_id/triggers/:trigger_id/errors

API Host: https://api.customer.io/v1/api

Retrieve per-user data file processing errors.

Parameters

campaign_id

The unique identifier for the campaign

trigger_id

The unique identifier for the trigger

start

use 0 for the first page of errors, and the value of "next" from the previous response for the next page.

limit

The number of errors to retrieve

curl -i https://api.customer.io/v1/api/campaigns/:id/triggers/:trigger_id/errors?start=0&limit=100 -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE 

If a broadcast trigger was sent to the API with the data_file_url or per_user_data blocks provided, and there were errors reported in the trigger status API call, this resource will allow you to retrieve pages of errors.

Important Usage Guidelines

API Host: https://beta-api.customer.io/v1/api

Here be dragons. Beta API features should be used with caution, and should be expected to change with little notice.

The API endpoints documented below are on the bleeding edge of what we’re building in our API. The API documentation is focused around calling via REST HTTP requests.

We encourage you to contact us at win@customer.io if you encounter issues, need clarifications or have requests for improvements. In addition, we’d love to hear about what you are building to help guide ongoing development.

This API is rate limited to 10 requests a second per workspace. Any requests beyond that are rejected with a http 429 status code.

/customers

API Host: https://beta-api.customer.io/v1/api

List customers

Parameters

email

Email address to search for matching customer profiles

curl -i https://beta-api.customer.io/v1/api/customers?email=test@example.com \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Calling the customers endpoint allows you to search Customer.io for a customer profile by email address.

/customers

API Host: https://beta-api.customer.io/v1/api

Search customers

Parameters

filter

Conditions to filter customers

start

The contination token to retrieve the next set of messages. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The number of messages to retrieve

# Find the first 2 customers in segment 7 and segment 5.
curl -i https://beta-api.customer.io/v1/api/customers?limit=2 \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"filter":{"and":[{"segment":{"id":7}},{"segment":{"id":5}}]}}'
  
# Find the first 10 unsubscribed customers
curl -i https://beta-api.customer.io/v1/api/customers?limit=10 \
  -X POST \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
  -H 'Content-Type:application/json' \
  -d '{"filter":{"attribute":{"field":"unsubscribed","operator":"eq","value":"true"}}}'

Posting the customers endpoint allows you to search Customer.io for a customer profiles matching a set of filters. The filter language is defined at https://customer.io/docs/documentation/api-triggered-data-format.html#general-syntax

/customers/:id/attributes

API Host: https://beta-api.customer.io/v1/api

List customer attributes

Parameters

id

The unique identifier for the customer

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

Retrieving customer attributes via the API returns all the attributes for a customer tracked in Customer.io by the passed Customer ID.

/customers/:id/segments

API Host: https://beta-api.customer.io/v1/api

List customer segments

Parameters

id

The unique identifier for the customer

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

Retrieving customer segments via the API returns all the segments a customer is a member of within Customer.io.

/customers/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent to a customer

Parameters

id

The unique identifier for the customer

start

The contination token to retrieve the next set of messages. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The number of messages to retrieve

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/customers/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/customers/:id/messages?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent to a customer via the API returns the metadata in most recent order.

/customers/:id/activities

API Host: https://beta-api.customer.io/v1/api

Get data about activities performed by or for a customer

Parameters

id

The unique identifier for the customer

start

The contination token to retrieve the next set of activities. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

type

The type of activity to return. This can be one of 'page', 'event', 'attribute_change', 'failed_attribute_change', 'stripe_event', 'drafted_email', 'failed_email', 'dropped_email', 'sent_email', 'spammed_email', 'bounced_email', 'delivered_email', 'triggered_email', 'opened_email', 'clicked_email', 'converted_email', 'unsubscribed_email', 'attempted_email', 'undeliverable_email', 'device_change', 'attempted_action', 'drafted_action', 'sent_action', 'delivered_action', 'bounced_action', 'failed_action', 'converted_action', 'undeliverable_action', 'opened_action', 'secondary:dropped_email', 'secondary:spammed_email', 'secondary:bounced_email', 'secondary:delivered_email', 'secondary:opened_email', 'secondary:clicked_email', 'secondary:failed_email'.

name

For 'event' the name of the event to search, and 'attribute_update' the name or attribute to search.

limit

The number of activities to retrieve

# Get metadata about the first two activities.
curl -i https://beta-api.customer.io/v1/api/customers/:id/activities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two activities.
curl -i https://beta-api.customer.io/v1/api/customers/:id/activities?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving data about activities performed by or for customer via the API returns the data in most recent order.

/campaigns

API Host: https://beta-api.customer.io/v1/api

List campaigns

curl -i https://beta-api.customer.io/v1/api/campaigns \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaigns via the API returns information regarding your Customer.io campaigns.

/campaigns/:id

API Host: https://beta-api.customer.io/v1/api

Get campaigns data

Parameters

id

The unique identifier of the template to be retrieved.

curl -i https://beta-api.customer.io/v1/api/campaigns/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a campaign that was previously created. Must supply a valid campaign ID.

/campaigns/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get campaign metrics

Parameters

id

The unique identifier for the campaign

period

Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.

steps

Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.

type

Specify metric type. Possible values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push' with the default being empty meaning aggregated metrics for all possible types.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=weeks \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=months \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaign metrics via the API returns metrics for a given Customer.io campaign. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

/campaigns/:id/triggers

API Host: https://beta-api.customer.io/v1/api

Get triggered campaigns

Parameters

id

The unique identifier for the campaign

curl -i https://beta-api.customer.io/v1/api/campaigns/:id/triggers \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving campaign triggers via the API returns data for a given Customer.io triggered campaign.

/campaigns/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent by a campaign

Parameters

id

The unique identifier for the campaign

start

The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The maximum number of messages to retrieve

type

Filter the messages metadata based on a message type. Allowable values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push'.

state

Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.

metric

Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a campaign via the API returns the metadata in reverse cronological order.

/newsletters

API Host: https://beta-api.customer.io/v1/api

List newsletters

curl -i https://beta-api.customer.io/v1/api/newsletters \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving newsletters via the API returns information regarding your Customer.io newsletters.

/newsletters/:id

API Host: https://beta-api.customer.io/v1/api

Get newsletter data

Parameters

id

The unique identifier for the newsletter

curl -i https://beta-api.customer.io/v1/api/newsletters/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a newsletter that was previously created. Must supply a valid newsletter ID.

/newsletters/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get newsletter metrics

Parameters

id

The unique identifier for the newsletter

period

Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.

steps

Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics?period=weeks \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving newsletter metrics via the API returns metrics for a given Customer.io newsletter campaign. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

/newsletters/:id/messages

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages sent by a newsletter

Parameters

id

The unique identifier for the newsletter

start

The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The maximum number of messages to retrieve

state

Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.

metric

Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a newsletter via the API returns the metadata in reverse cronological order.

/segments

API Host: https://beta-api.customer.io/v1/api

Create manual segment

Parameters

name

Name of the manual segment

description

Description of the segment

curl -H "Content-Type: application/json" --request POST -d '{"segment":{"name":"Manual Segment 1","description":"Description for segment"}}' \
https://beta-api.customer.io/v1/api/segments \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Creates a manual segment. Must supply a valid segment name.

/segments

API Host: https://beta-api.customer.io/v1/api

List segments

curl -i https://beta-api.customer.io/v1/api/segments \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving segments via the API returns information regarding your Customer.io segments.

/segments/:id

API Host: https://beta-api.customer.io/v1/api

Get segment data

Parameters

id

The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a segment that was previously created. Must supply a valid segment ID.

/segments/:id/used_by

API Host: https://beta-api.customer.io/v1/api

Get dependencies of a segment

Parameters

id

The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id/used_by \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the campaigns and newsletters used by a given segment. Must supply a valid segment ID.

/segments/:id/customer_count

API Host: https://beta-api.customer.io/v1/api

Get number of customers in a segment

Parameters

id

The unique identifier for the segment

curl -i https://beta-api.customer.io/v1/api/segments/:id/customer_count \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves membership count for a given segment. Must supply a valid segment ID.

/segments/:id/membership

API Host: https://beta-api.customer.io/v1/api

Get the membership of a segment

Parameters

id

The unique identifier for the segment

start

The contination token to retrieve the next set of ids

limit

The maximum number of ids to retrieve

# Get the first two ids,
curl -i https://beta-api.customer.io/v1/api/segments/:id/membership?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get the next two ids.
curl -i https://beta-api.customer.io/v1/api/segments/:id/membership?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the ids of the customers in a given segment. Must supply a valid segment ID. Note that the continuation token may end with an ‘=’ character, so be sure to query escape the token.

/segments/:id

API Host: https://beta-api.customer.io/v1/api

Delete an existing manual segment by id

Parameters

id

The segment id

curl -curl -X DELETE https://beta-api.customer.io/v1/api/segments/1 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

/msg_templates

API Host: https://beta-api.customer.io/v1/api

Get message template data

Parameters

start

The continuation token to retrieve the next set of template data. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The number of message template data to retrieve per request, maximum of 100 and a default of 10.

sort

Set the chronological order of the response. Allowable values are 'asc' for chronological order, the default value, and 'desc' for reverse-chronological order.

# Get data about the first two templates.
curl -i https://beta-api.customer.io/v1/api/msg_templates?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get data about the next two templates.
curl -i https://beta-api.customer.io/v1/api/msg_templates?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of message templates that were previously created.

/msg_templates/:id

API Host: https://beta-api.customer.io/v1/api

Get message template data

Parameters

id

The unique identifier of the template to be retrieved.

curl -i https://beta-api.customer.io/v1/api/msg_templates/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a message template that was previously created. Must supply a valid template ID.

/msg_templates/:id/metrics

API Host: https://beta-api.customer.io/v1/api

Get message template metrics

Parameters

id

The unique identifier of the message template to retrieve metrics of.

period

Specify metric period. Possible values are 'hours', 'days', 'weeks', 'months', with a default being 'days'.

steps

Integer specifying how many steps to return. Defaults to the maximum number of timeperiods available, or 12 when using the 'months' period.

# Get by days (maximum being 192 days)
curl -i https://beta-api.customer.io/v1/api/msg_templates/:id/metrics?period=days \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

# Get by weeks (maximum being 17 weeks)
curl -i https://beta-api.customer.io/v1/api/msg_templates/:id/metrics?period=weeks \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metrics for a message template via the API returns metrics for a given Customer.io message template. The maximum amount of data is always retrieved, the metrics being in time order from least recent to most recent.

/messages

API Host: https://beta-api.customer.io/v1/api

List metadata about messages

Parameters

start

The contination token to retrieve the next set of message metadata. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The maximum number of message metadata to retrieve

state

Filter the message metadata based on a state. Allowable values are 'failed', 'sent', 'drafted', 'attempted'.

type

Filter the messages metadata based on a message type. Allowable values are 'email', 'webhook', 'twilio', 'urban_airship', 'slack', 'push'.

metric

Filter the message metadata based on a metric. Allowable values are 'created', 'drafted', 'attempted', 'sent', 'delivered', 'opened', 'clicked', 'converted', 'bounced', 'spammed', 'unsubscribed', 'dropped', 'failed', 'undeliverable'.

campaign_id

Filter the message metadata based on a campaign id.

newsletter_id

Filter the message metadata based on a newsletter id.

template_id

Filter the message metadata based on a template id.

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/messages?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two messages.
curl -i https://beta-api.customer.io/v1/api/messages?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving metadata about messages sent by a newsletter via the API returns the metadata in reverse cronological order.

/messages/:id

API Host: https://beta-api.customer.io/v1/api

Get metadata about messages

Parameters

id

The unique identifier for the message

curl -i https://beta-api.customer.io/v1/api/messages/:id \
  -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the metadata about a message that was previously created. Must supply a valid message ID.

/exports

API Host: https://beta-api.customer.io/v1/api

List exports

curl -i https://beta-api.customer.io/v1/api/exports \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving exports via the API returns information regarding your Customer.io exports.

/exports/:id

API Host: https://beta-api.customer.io/v1/api

Get export data

Parameters

id

The unique identifier for the export

curl -i https://beta-api.customer.io/v1/api/exports/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of an export that was previously created. Must supply a valid export ID.

/exports/:id/download

API Host: https://beta-api.customer.io/v1/api

Download an export

Parameters

id

The unique identifier for the export

curl -i https://beta-api.customer.io/v1/api/exports/:id/download \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Downloading an export returns an signed link to download the content. The link expires after 15 minutes.

/exports/customers

API Host: https://beta-api.customer.io/v1/api

Create customer export

Parameters

attributes

The set of user attributes that should be included in the export

filters

The filter conditions that will determine which customers to include in the export

curl -i https://beta-api.customer.io/v1/api/exports/customers \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-d '{"filters":{"and":[{"segment":{"id":7}},{"segment":{"id":5}}]}}'

Creates a customer export and returns the export record data

/exports/deliveries

API Host: https://beta-api.customer.io/v1/api

Create delivery export

Parameters

newsletter_id

The unique identifier of the newsletter the export is for

campaign_id

The unique identifier of the campaign the export is for

template_ids

The unique identifiers of the templates the export is for

start

The unix timestamp that denotes the beginning of the period the export is for

end

The unix timestamp that denotes the end of the period the export is for

attributes

The attributes that should be included in the export

and_filters

The and conditions that denote which deliveries should be included in the export

or_filters

The or conditions that denote which deliveries should be included in the export

curl -i https://beta-api.customer.io/v1/api/exports/deliveries \
-X POST \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \
-d {"newsletter_id": "10", "start": 1517529600, "end": 1517702400}

Creates a delivery export and returns the export record data

/activities

API Host: https://beta-api.customer.io/v1/api

Get data about activities

Parameters

start

The contination token to retrieve the next set of activities. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

type

The type of activity to return. This can be one of 'page', 'event', 'attribute_change', 'failed_attribute_change', 'stripe_event', 'drafted_email', 'failed_email', 'dropped_email', 'sent_email', 'spammed_email', 'bounced_email', 'delivered_email', 'triggered_email', 'opened_email', 'clicked_email', 'converted_email', 'unsubscribed_email', 'attempted_email', 'undeliverable_email', 'device_change', 'attempted_action', 'drafted_action', 'sent_action', 'delivered_action', 'bounced_action', 'failed_action', 'converted_action', 'undeliverable_action', 'opened_action', 'secondary:dropped_email', 'secondary:spammed_email', 'secondary:bounced_email', 'secondary:delivered_email', 'secondary:opened_email', 'secondary:clicked_email', 'secondary:failed_email'.

name

For 'event' the name of the event to search, and 'attribute_change' the name or attribute to search.

deleted

If true, also return activities for deleted customers.

customer_id

Only find activities for a given customer id.

limit

The number of activities to retrieve

# Get metadata about the first two activities.
curl -i https://beta-api.customer.io/v1/api/activities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get metadata about the next two activities.
curl -i https://beta-api.customer.io/v1/api/activities?limit=2&start=ZAEGAQLQ0_wRgPsS6F0cuig_iQ== \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieving data about activities the API returns the data in most recent order.

The activities API retrieves the same data as seen in the UI which only goes back approximately 30 days.

/sender_identities

API Host: https://beta-api.customer.io/v1/api

Get sender identities data

Parameters

start

The continuation token to retrieve the next set of sender identity data. Note that the continuation token may end with an '=' character, so be sure to query escape the token.

limit

The number of sender identity data to retrieve per request, maximum of 100 and a default of 10.

sort

Set the chronological order of the response. Allowable values are 'asc' for chronological order, the default value, and 'desc' for reverse-chronological order.

# Get data about the first two identities.
curl -i https://beta-api.customer.io/v1/api/sender_identities?limit=2 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE
# Get data about the next two identities.
curl -i https://beta-api.customer.io/v1/api/sender_identities?limit=2&start=MDox \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of sender identities that were previously created.

/sender_identities/:id

API Host: https://beta-api.customer.io/v1/api

Get sender identity data

Parameters

id

The unique identifier of the sender identity to be retrieved.

curl -i https://beta-api.customer.io/v1/api/sender_identities/:id \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the details of a sender identity that was previously created.

/sender_identities/:id/used_by

API Host: https://beta-api.customer.io/v1/api

Get sender identity usage data.

Parameters

id

The unique identifier of the sender identity usage data is to be retrieved for.

curl -i https://beta-api.customer.io/v1/api/sender_identities/:id/used_by \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the usage details of a sender identity that was previously created.

/reporting_webhooks/

API Host: https://beta-api.customer.io/v1/api

Create a new reporting webhook settings

Parameters

endpoint

The webhook URL

events

The webhook settings as json

full_resolution

Determines if only the first time or every time the event occurs.

curl -i https://beta-api.customer.io/v1/api/exports/customers \
-h "Content-Type: application/json" \
--request POST \
-d '{"endpoint":"http://example.com/webhook","events":{"customer_subscribed":false,"customer_unsubscribed":true,"email_attempted":true,"email_bounced":false,"email_clicked":true,"email_converted":false,"email_delivered":true,"email_drafted":false,"email_dropped":true,"email_failed":false,"email_opened":true,"email_sent":false,"email_spammed":true,"email_unsubscribed":false},"full_resolution":true}' \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

/reporting_webhooks/

API Host: https://beta-api.customer.io/v1/api

Get reporting webhook settings

curl -i https://beta-api.customer.io/v1/api/reporting_webhooks/ \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

Retrieves the settings of a reporting webhook.

/reporting_webhooks/:id

API Host: https://beta-api.customer.io/v1/api

Create a new reporting webhook settings

Parameters

id

The webhook id

endpoint

The webhook URL

events

The webhook settings as json

full_resolution

Determines if only the first time or every time the event occurs.

curl -i https://beta-api.customer.io/v1/api/exports/customers \
-h "Content-Type: application/json" \
--request PUT \
-d '{"endpoint":"http://example.com/webhook2","events":{"customer_subscribed":false,"customer_unsubscribed":true,"email_attempted":true,"email_bounced":false,"email_clicked":true,"email_converted":false,"email_delivered":true,"email_drafted":false,"email_dropped":true,"email_failed":false,"email_opened":true,"email_sent":false,"email_spammed":true,"email_unsubscribed":false},"full_resolution":false}' \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE

/reporting_webhooks/:id

API Host: https://beta-api.customer.io/v1/api

Delete an existing webhook settings

Parameters

id

The webhook id

curl -curl -X DELETE https://beta-api.customer.io/v1/api/reporting_webhooks/1 \
-u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE