Collections (Beta)

🤠 Howdy partner! Welcome to the frontier of Customer.io! Collections is a new beta feature that lets you store data in your workspace for use in campaigns.

As you’re one of the first to try this out, we have a request: stay in touch! We’re releasing this early so your feedback can influence what we build. We’d love to know: What’s working well? Where did you get stuck? What was confusing? What do you dream this will become? Don’t hesitate - we’re friendly folk! product@customer.io

What’s a Collection?

A collection is a new type of data in Customer.io that’s separate from people or events in your account. They represent any set of “things” that exist in your business. For instance, a Collection could be a list of upcoming events, promotions/coupons, or available classes.

You should store this data in Customer.io when it’s helpful to be able to sort through the Collection to identify a specific set of data that you want to include in a message, tailored to the data you know about each person. Let’s take the example of an online learning service. By storing all the courses offered in a Collection, you could retrieve the specific set of classes that are relevant for each individual person and list them in an email.

From a technical standpoint, Collections are very flexible. They’re simply a list of JSON objects - no schemas or indexes are required.

Creating a Collection

You can upload your collection as a JSON file, CSV, or by pointing to a Google Sheet. If you upload a CSV file or Google Sheet, we expect your file to be a simple table with headers, as in this example.

To upload your collection:

  1. Select Content > Collections in the navigation menu.
  2. Click Add Collection.
  3. Select your collection file.
  4. Click Add Collection.
Collection uploads are limited to 10MB.
add_collection.png
add_collection.png

Alternatively, you can can add a Collection using the API.

Adding Collection Data to your Messages

Now that you’ve added a Collection, the next step is to use them in your campaigns. The power of Collections is that you can query the Collection as part of a campaign workflow, meaning that you can retrieve only the Collection items relevant to that particular person and campaign.

First, add a “Query Collection” action to your campaign

When one of your customers reaches this part of the workflow, we’ll retrieve the data you want to use in subsequent messages.

query.gif
query.gif

Build a query to retrieve the rows relevant to the person

Select your new collection in the workflow, give it a name, and press “Edit Query” to get started. You’ll arrive at our new query builder:

Screen Shot 2020-07-09 at 3.45.33 PM.png
Screen Shot 2020-07-09 at 3.45.33 PM.png

To show how this works, lets take the example of a service that delivers online courses. Let’s say you want to query for a list of courses that are appropriate for the skill level of the person who triggered the campaign.

First, select the Profile Attribute you want to store the results of the query in, something like next_courses. Then, select the Collection you want to query. Next is the exciting part: press the Add query condition button and use it to filter for the courses you want to send an email about. For example, all courses where the Collection attribute level is equal to the profile attribute skill_level.

Screen_Shot_2020-05-15_at_2.59.28_PM.png
Screen_Shot_2020-05-15_at_2.59.28_PM.png

When you add this condition, you’ll see a preview on the right side or on the Preview tab shows what Collection rows would be returned for the person you have selected in the Sample Data panel on the left side.

When this query is run as part of a campaign, the rows from this Collection that match your query will be stored in the profile attribute you selected formatted as JSON. If you choose to return only one result, the result will be a JSON object, or an array if you choose to return multiple.

Use Liquid to add Collection data to your message

Now that you’ve set up your query, it’s time to use the Collection data in a message! As the results of Collections queries are stored as JSON arrays in customer attributes, you work with the results in Liquid in all the familiar ways.

For example, you can use a for loop to to show the names of each of the courses returned by the query in the previous section:

{% for item in customer.next_courses %}
  {{ item.name }}
{% endfor %}

Also helpful are Liquid’s array filters, such as first, last, and map which allow you to select specific items or attributes. For example:

{% assign first_course = customer.next_courses | first %}

If you limited your query to a single result, then the attribute will be a object rather than an array. You can instead directly access the name and course description:

{{ promo_course.name }}
{{ promo_course.description }}

Collections API

The endpoints for Collections are available via our beta App API:

  • US region: https://beta-api.customer.io/v1/api
  • EU region: https://beta-api-eu.customer.io/v1/api

If you haven’t used this API before, you’ll find authentication data in our API docs.

Creating a new Collection:

POST:/v1/api/collections

Create a new collection by providing both a name and either a array of JSON objects as data, or a url to download the data from.

{
"name": "collection name",
"data": [ { row }, { row } ],
"url": "https://some.domain/some_file"
}

If you choose to provide a URL the data can either be a file containing JSON (either an array, or newline delimited) or a CSV file. Ensure that you provide a Content-Type definition so that we know how to parse the data. If no Content-Type is provided the file extension is used. We default to JSON parsing otherwise.

The URL can also be a google sheet, shared with cio_share@customer.io (as documented at https://customer.io/docs/uploading-people).

Once created, a Collection has the following JSON definition:

"bytes": bytes_of_data_in_collection,
"created_at": 1589471110,
"updated_at": 1589471132
"id": 1,
"name": collection_name
"rows": number_of_rows_in_collection,
"schema": ["name1", "name2", "name3" ],

The schema will have a list of all attributes used by any items in the Collection, but remember that we don’t enforce that all items will have this set of attributes.

Retrieve info about of a Collection you’ve already created

GET:/v1/api/collections/:id

Get the details of a collection with the given id. This does not include the content.

Retrieve the content of a Collection you’ve already created

GET:/v1/api/collections/:id/content

Returns the entire content of the collection with the given id.

Retrieve a list of all your Collections

GET:/v1/api/collections

Returns the details (but not content) for all of your Collections:

{"collections": [collection1, collection2}}

Update the content of a Collection

PUT:/v1/api/collections/:id/content

Provide the content of a Collection as a JSON encoded text, or a CSV encoded data. This will replace all the content for the Collection. For example:

{"name":"Steak","price":20,"quantity":10,"can_deliver":false}

Update the name and content of a Collection

PUT:/v1/api/collections/:id

Update an existing collection. If name or data or url aren’t provided the associated data is not updated. This will replace all the content for the Collection.

{
"name": "collection name",
"data": [
  {"name":"Hot Dog","price":2,"quantity":1,"can_deliver":true},
  {"name":"Pizza","price":10,"quantity":2,"can_deliver":true},
  {"name":"Steak","price":20,"quantity":10,"can_deliver":false} ]
}
OR
{
  "name": "collection name",
  "url": "https://docs.google.com/spreadsheets/d/1JplGcPy7oyj5ZELtar1Ko81F_fJnSDEhsptmZVO38BA/edit#gid=0"
}

Delete a Collection

DELETE:/v1/api/collections/:id

Deletes the collection with the given id.

What’s not working (yet)

As you can tell, we’re just getting started! There a few gaps we’re aware of. Get in touch and let us know which of these you’d like us to prioritize:

  • Collections cannot be used in Newsletters
  • We know it’s a pain to store this data in attributes for later reference in messages. We’re experimenting with several ideas for storing collection data directly within the workflows.

Let us know what you do with Collections!

What comes next? You tell us! We’re making this available early so you can help us understand what you’d most like to see from Collections. Get in touch at product@customer.io.

Copied to clipboard!