PUT /api/v1/customers/{identifier}

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.

Servers

https://track.customer.io

Path parameters

Name	Type	Required	Description
`identifier`		Yes	The unique value representing a person. The values you use to identify a person may be an `id`, `email` address, or the `cio_id` (when updating people), depending on your workspace settings. When you reference people by `cio_id`, you must prefix the value with `cio_`.

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`id`	String	No	A customer's ID. You can set a person's ID if you identify them by email (in the path); you can update this value if you identify a person by `cio_id`.
`email`	String	No	The email address of the customer.
`cio_subscription_preferences`	Object	No	Stores your audience's subscription preferences if you enable our subscription center feature. These items are set automatically when people use the unsubscribe link in your messages, but you can set preferences outside the subscription flow. To update select topic preferences while preserving those set for other topics, use JSON dot notation `"cio_subscription_preferences.topics.topic_<topic ID>":<boolean>`.
`cio_subscription_preferences.topics`	Object	No	Contains active topics in your workspace, named `topic_<id>`.
`anonymous_id`	String	No	An identifier for an anonymous event, like a cookie. If set as an attribute on a person, any events bearing the same anonymous value are associated with this person. This value must be unique and is not reusable.
`unsubscribed`	Boolean	No	If true, a person is unsubscribed from all messages. If false, or absent, a person is eligible to receive messages as determined by their `cio_subscription_preferences`. Like subscription preferences, this attribute is automatically set or updated when a person clicks the "unsubscribe" link in your emails.
`cio_relationships`	Object	No	Describes relationships to an entity—a non-person object in Customer.io, like a company, educational course, job board, etc.
`cio_relationships.action`	String	No	This determines whether the `relationships` array adds relationships to a person or removes them from a person. Possible values: `"delete_relationships"` `"add_relationships"`
`cio_relationships.relationships[]`	Array	No	Each object in the array represents a relationship you want to add to, or remove from, a person.
`cio_relationships.relationships[].identifiers`	Object	Yes	Represents an individual object, where the `object_type_id` represents the type of object and the `object_id` is the individual identifier for the object.
`cio_relationships.relationships[].identifiers.object_id`	String	Yes	The unique identifier for an object. If you use an `object_id` that already exists, we'll update the object accordingly.
`cio_relationships.relationships[].identifiers.object_type_id`	String	Yes	The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
`cio_relationships.relationships[].relationship_attributes`	Object	No	Coming January 2024 - If we have not rolled out relationship attributes to your account yet and you send them with your request, your request will go through but we won't store your relationship attributes. The attributes associated with a relationship. Passing null or an empty string removes the attribute from the relationship.
`created_at`	Integer	No	The Unix timestamp when the user was created.
`_update`	Boolean	No	If you perform multiple requests in rapid succession when you create a person, there's a danger that you could create multiple profiles. If you know that a profile already exists and you want to update it, set `_update:true`, and Customer.io will not create a new profile, even if the `identifier` in the path isn't found. If the identifiers in your path or request don't belong to an existing person, the request produces a Failed Attribute Change event in your activity log.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.