This endpoint lets you create, update, or delete a single person or object—including managing relationships between objects and people.

An "object" is any kind of non-person entity that you want to associate with one or more people—like a company, an educational course that people signed up for, a product, etc.

Your request must be smaller than 32kb.

This endpoint lets you batch requests for different people and objects in a single request. Each object in your array represents an individual "entity" operation—it represents a change for a person, an object, or a delivery.

You can mix types in this request; you are not limited to a batch containing only objects or only people. An "object" is a non-person entity that you want to associate with one or more people—like a company, an educational course that people enroll in, etc.

Your request must be smaller than 500kb.

This endpoint returns the appropriate region and URL for your Track API credentials. Use it to determine the URLs you should use to successfully complete other requests.

You can perform this operation against either of the track API regional URLs; it returns your region in either case.

This endpoint also returns an environment_id, which represents the workspace the credentials are valid for.

Adds or updates a person.

If your request does not include cio_id and the identifiers in the request body do not belong to a person, your request adds a person.

If a person already exists with the identifier in the request path, your request updates that person. If the identifier in the path does not belong to a person but you use an identifier in your request body that does belong to a person, your request updates the person and assigns them the identifier in the path.

If the identifier in the path and request body belong to different people, your request may return 200 OK but produce an Attribute Update Failure for the identifier in the payload.

If you want to update a person's identifiers after they are set, you must reference them using their cio_id in the format cio_<cio_id_value>—unless when updating an email with the Allow updates to email using ID setting enabled. You can get the cio_id value from the App API. If your request includes a cio_id, we'll attempt to update that person, including any identifiers in the request. If the cio_id does not exist or belongs to a person who was deleted, we'll drop the request.

For workspaces using email as an identifier, email is case-insensitive. The addresses person@example.com and PERSON@example.com would represent the same person.

Deleting a customer removes them, and all of their information, from Customer.io.

NOTE: Calls that update customers by ID can also create a customer. If you send data to Customer.io through other means (like the Javascript snippet), after you delete a customer, you may accidentally recreate the customer. You cannot delete a customer using the Javascript snippet alone.

Customers can have more than one device. Use this method to add iOS and Android devices to, or update devices for, a customer profile.

Remove a device from a customer profile. If you continue sending data about a device to Customer.io, you may inadvertently re-add the device to the customer profile.

Delete a customer profile and prevent the person's identifier(s) from being re-added to your workspace. Any future API calls or operations referencing the specified ID are ignored. If you suppress a person in a workspace set that identifies people by email or ID and both identifiers are set, both the person's email and ID are suppressed.

Unsuppressing a profile allows you to add the customer back to Customer.io. If you unsuppress a person in a workspace set that identifies people by email or ID and the suppressed person had both an email and ID, both the person's email and ID are unsuppressed.

Unsuppressing a profile does not recreate the profile that you previously suppressed. Rather, it just makes the identifier available again. Identifying a person after unsuppressing them creates a new profile, with none of the history of the previously suppressed identifier.

This endpoint lets you set a global unsubscribed status outside of the subscription pathways native to Customer.io. If you use custom unsubscribe links, you can host a custom unsubscribe page and use this API to send unsubscribe data, associated with a particular delivery, to Customer.io.

NOTE: This endpoint requires a Content-type: application/json header. This endpoint does not require an Authorization header.

Your request sets a person's unsubscribed attribute to true, attributes their unsubscribe request to the individual email/delivery that they unsubscribed from, and lets you segment your audience based on email_unsubscribed events when you use a custom subscription center.

If you use a custom subscription center (managing subscriptions to various types of messages with custom attributes), this request does not set a custom attribute. You must perform a separate request to update a person's custom subscription attributes.

Merge two customer profiles together. The payload contains primary and secondary profile objects. The primary profile remains after the merge and the secondary is deleted. This operation is not reversible.

The following information is merged into the primary profile from the secondary profile:

• Attributes that are not set, or are empty, on the primary.
• The most recent 30-days of event history. Events merged from the secondary person cannot trigger campaigns.
• Manual segments that the primary person did not already belong to.
• Message delivery history.
• Campaign journeys that the primary person has not entered. If the secondary person has started a journey that the primary person has not, the primary person continues on that campaign journey after the merge. If the secondary person has completed journeys that the primary person has not, the primary person gains these historical journeys after the merge. This may be important for determining entry (or re-entry) criteria for subsequent campaigns, segments, etc.

Send an event associated with a person, referenced by the identifier in the path. There are three defined event type values: page, screen and event. Page and screen events represent website page views and mobile app screen views respectively; the name for these event types is intended to be the page or screen a person visited or viewed. Any other event, is given the event type.

We automatically trim leading and trailing spaces from event names.

Reserved Properties

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

• from_address
• recipient
• reply_to

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

An anonymous event represents a person you haven't identified yet. When you identify a person, you can set their anonymous_id attribute. If event merging is turned on in your workspace, and the attribute matches the anonymous_id in one or more events that were logged within the last 30 days, we associate those events with the person. If you associate an event with a person within 72 hours of the timestamp on the event, you can trigger campaigns from the event.

There are three possible event type values: page, screen and event. Page and screen events represent website page views and mobile app screen views respectively; the name for these event types is intended to be the page or screen a person visited or viewed. Any other event, is given the event type.

Note: Avoid using names with leading or trailing spaces, because you can't reference event names with leading or trailing spaces in campaigns, etc. In workspaces created after September 21, 2021, we trim leading and trailing spaces from event names automatically to fix this issue.

This endpoint helps you report metrics from channels that aren't native to Customer.io or don't rely on our SDKs. When we deliver a message, we include a CIO-Delivery-ID header. This is the delivery_id in the payload. You can use it as a UTL and you can pass it as a UTM parameter in links, etc to track metrics when people click, convert, etc.

While this endpoint still works, you should take advantage of our universal metrics endpoint. It supports channels besides push and lets you provide additional information with some metrics.

Use this endpoint to report device-side push metrics—opened, converted, and delivered—back to Customer.io, so you can track the effectiveness of your push notifications. Customer.io has no way of knowing about these metrics, or associating metrics with a specific message, unless you report them back to us.

When Customer.io delivers a push notification, we include CIO-Delivery-ID and CIO-Delivery-Token parameters. Reference these in your payload as the delivery_id and device_id respectively with the type of device-side event metric that you want to associate with your push notification and the person represented by the device_id.

Submit a form response. If Customer.io does not recognize the form_id we create a new form connection (found on the Data & Integrations > Integrations > Forms page). Form submissions with the same ID are treated as submissions from the same form.

The data object must contain at least one of id or email (depending on the identifiers supported in your workspace)—or a field that is mapped to one of these identifiers—to identify the form respondent. If the person who submitted the form does not already exist, we create them (like an identify request).

Additional keys in the data object represent form fields and values from the form that a person submitted. By default, we map form fields in your request directly to attributes, e.g. if you have a form field called first_name, we map that field to the first_name attribute.

NOTES:

• You cannot disable fields that you send to this API. If you send a field (as data) to this API, we'll include it in the form submission.
• If an identifier in your form is called something like email_address rather than email in your initial request, you'll receive a 400, but we'll still add your form on the Data & Integrations > Integrations > Forms page. You can then re-map your email_address field to email, and your form will begin working normally.
• Customer.io reserves form_id, form_name, form_type, form_url, and form_url_param keys. If your request includes these keys, Customer.io ignores them.

Add people to a manual segment by ID. You are limited to 1000 customer IDs per request.

This endpoint lets you add people to manual segments, but a segment must exist before you can add people to it. You can create and find manual segments using the App API.

When you call this API, you can pass an id_type query parameter determining the type of identifier you want to use, id, email, or cio_id; If you don't pass this parameter, it defaults to id. The request body always uses ids, even though it'll accept either IDs, emails, or cio_ids depending on the query parameter. Everybody in the payload must use the same kind of identifier; we'll ignore values in the ids array that don't match the id_type parameter.

NOTE: You cannot add people to data-driven segments using the API. See our documentation on segments for more information about segments.

You can remove users from a manual segment by ID. You are limited to 1000 customer IDs per request.

This endpoint requires people to have id attributes. If your workspace does not use id as an identifier, or you have not assigned people id values, you cannot remove people from manual segments using the API. Our user interface does not have this limitation. You can remove people from manual segments through the UI as a part of a campaign workflow.

NOTE: You cannot remove people from data-driven segments using the API. See our documentation on segments for more information about segments.