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/

Currently, this endpoint is only used for sending API triggered broadcasts.

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

Limits

Note: If any of the limits below appear to be too restrictive for your needs, please contact support to let us know your situation as we may be able to accommodate your special circumstances.

Identify Limits

Event Limits

API Triggered Broadcast Limits

* For larger data sets, please use data_file_url to supply a link to a file that contains your merge data as attempting to send too much data in a single API call will fail.

Rate Limits

• For calls made to track.customer.io (our Behavioral Tracking API), there is no hard rate limit at which point Customer.io will drop your data. We ask that you limit these requests to 30 requests per second for both active data integrations, as well as historical backfill scripts. If you need to exceed 30 requests per second, please contact us first.
• Calls made to api.customer.io and beta-api.customer.io (our API and beta API) are hard limited to 10 requests per second.
• API Triggered Broadcasts are not limited by calls per second but are limited by the number of triggers you can have queued at once instead.

If track.customer.io calls unexpectedly exceed 30 requests per second, 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.

Authentication

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

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 using a Tracking API Key over HTTP Basic Auth.

To authenticate, provide your Site ID as the username, and your secret API key as the password. You can find these values by visiting the Tracking API Keys page directly, or by clicking the Integrations link in the left-hand menu of your Customer.io account and choosing Customer.io API > Manage API Credentials > Tracking API Keys.

Nothing will work unless you include both your Site ID and your API Key

/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 300 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 trigger broadcast campaigns.

To authenticate, use the same scheme as our Track API

The API documentation is focused around the REST HTTP API, but we will provide equivalent 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.

This endpoint is rate limited to one request every 10s. Please reach out to win@customer.io if you have a use case that exceeds this limit.

/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.

Authentication

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

curl -i https://beta-api.customer.io/v1/api/campaigns \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

All requests to the Customer.io Beta API should be authenticated using an App API Key.

To authenticate, provide your key as a Bearer token in a HTTP Authorization header. You can create and manage your API keys by visiting your App API Keys page directly or by clicking the Integrations link in the left-hand menu of your Customer.io account and choosing Customer.io API > Manage API Credentials > App API Keys.

This App API key is required for all requests to the Beta API, usage of tracking API keys has been deprecated.

/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 \
-H "Authorization: Bearer YOUR-APP-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 continuation 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 \
  -H "Authorization: Bearer YOUR-APP-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 \
  -H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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 continuation 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 \
-H "Authorization: Bearer YOUR-APP-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== \
-H "Authorization: Bearer YOUR-APP-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 continuation 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 \
-H "Authorization: Bearer YOUR-APP-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== \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

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 45 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics?period=months \
-H "Authorization: Bearer YOUR-APP-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/metrics/links

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

Get campaign link 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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

unique

Bool, defaults to false, which is the aggregate total number of clicks for the link. If set to true, returns the unique number of customer clicks for a given link.

# Get by days (maximum being 45 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics/links \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics/links?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/metrics/links?period=months \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

Retrieving campaign link metrics via the API returns metrics for individual link clicks in 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/actions

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

List campaign actions

curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

/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 continuation 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'.

metric

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

drafts

Select whether to retrieve drafted messages or not

# Get metadata about the first two messages.
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/messages?limit=2 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

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

/campaigns/:id/actions/:action_id

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

Get action of a campaign by id.

Parameters

id

The unique identifier of the campaign.

action_id

The unique identifier of the action.

curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

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

/campaigns/:id/actions/:action_id

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

Update the content of a campaign action

Parameters

id

The unique identifier of the campaign.

action_id

The unique identifier of the action.

recipient

Recipient address for the action.

body

Body content for the action. Cannot be modified if you created this content with our drag-and-drop email editor.

subject

Subject for the action, applies to email actions only.

headers

A list of headers in the form [{"name": "HeaderName", "value": "HeaderValue"},{...}].

url

URL to send a webhook to, applies to webhook actions only.

method

HTTP request type for a webhook, applies to webhook actions only.

from_id

sender_identity id to use as the from address for this action.

reply_to_id

sender_identity id to use in the ReplyTo header for an email, applies to email actions only.

curl -XPUT -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE" \
-d '{"recipient": "sendtome@example.com"}'

Updates the content of a campaign action

This endpoint is only available when using an App API Key

/campaigns/:id/actions/:action_id/metrics

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

Get action metrics of a campaign

Parameters

id

The unique identifier for the campaign

action_id

The unique identifier for the action

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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

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 45 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics?period=months \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

/campaigns/:id/actions/:action_id/metrics/links

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

Get campaign action link metrics

Parameters

id

The unique identifier for the campaign

action_id

The unique identifier for the action

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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

unique

Bool, defaults to false, which is the aggregate total number of clicks for the link. If set to true, returns the unique number of customer clicks for a given link.

# Get by days (maximum being 45 days)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics/links \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics/links?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/campaigns/:id/actions/:action_id/metrics/links?period=months \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

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

/newsletters

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

List newsletters

curl -i https://beta-api.customer.io/v1/api/newsletters \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

# Get by days (maximum being 45 days)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics?period=weeks \
-H "Authorization: Bearer YOUR-APP-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/metrics/links

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

Get newsletter link 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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

unique

Bool, defaults to false, which is the aggregate total number of clicks for the link. If set to true, returns the unique number of customer clicks for a given link.

# Get by days (maximum being 45 days)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics/links \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics/links?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/metrics/links?period=months \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

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

/newsletters/:id/contents

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

Get all content variants of a newsletter

Parameters

id

The unique identifier for the newsletter

curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

Retrieves all content variants of a newsletter. Must supply a valid newsletter ID.

/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 continuation 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

metric

Filter the message metadata based on a metric. Allowable values are 'created', '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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

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

/newsletters/:id/contents/:content_id

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

Get a specific message variant of a newsletter.

Parameters

id

The unique identifier for the newsletter

content_id

The unique identifier for this newsletter content variant

curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

/newsletters/:id/contents/:content_id

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

Update a newsletter content variant

Parameters

id

The unique identifier of the newsletter.

content_id

The unique identifier for this newsletter content variant.

recipient

Recipient email address.

body

HTML email body. Cannot be modified if you created this content with our drag-and-drop email editor.

subject

Email subject.

headers

A list of email headers in the form [{"name": "HeaderName", "value": "HeaderValue"},{...}].

from_id

sender_identity id to use as the from address.

reply_to_id

sender_identity id to use in the ReplyTo header.

curl -XPUT -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE" \
-d '{"recipient": "sendtome@example.com"}'

Modify a single newsletter content variant

This endpoint is only available when using an App API Key

/newsletters/:id/contents/:content_id/metrics

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

Get metrics for a specific message variant of a newsletter

Parameters

id

The unique identifier for the newsletter

content_id

The unique identifier for this newsletter content variant

curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id/metrics \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

Retrieves the message metrics of a single newsletter content variant. Must supply valid newsletter and content IDs.

/newsletters/:id/contents/:content_id/metrics/links

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

Get newsletter content link metrics

Parameters

id

The unique identifier for the newsletter

content_id

The unique identifier for this newsletter content variant

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. Maximum timeperiods available are 24 hours, 45 days, 12 weeks and 120 months.

unique

Bool, defaults to false, which is the aggregate total number of clicks for the link. If set to true, returns the unique number of customer clicks for a given link.

# Get by days (maximum being 45 days)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id/metrics/links \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by weeks (maximum being 12 weeks)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id/metrics/links?period=weeks \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

# Get by months (maximum being 120 months)
curl -i https://beta-api.customer.io/v1/api/newsletters/:id/contents/:content_id/metrics/links?period=months \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"

Retrieving link metrics for newsletter content variants via the API will return metrics for individual link-clicks for a given content_id.

/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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-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 \
-H "Authorization: Bearer YOUR-APP-API-KEY-HERE"