Sign in
Track Customers

Add or update a customer

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.

Tip: If your workspace identifies people by both email and id, and you send an identify call with a new id but an email that already belongs to someone, we update the existing person rather than creating a new one. The existing person gets the new id. This is a common source of confusion during testing—if you're generating new IDs but reusing the same email address, you're updating one person repeatedly, not creating multiple people.

put/api/v1/customers/{identifier}

Path parameters

string required

The unique identifier for a person that you want to create or modify.

OR
string required

A person's email address. If adding a new person in an email-based workspace, you must use this value.

OR
string cio_[a-zA-Z0-9]* required

A canonical identifier assigned by Customer.io when you add a person. When referencing a person by this value, you must prefix the value with cio_. You can look up a person using the App API to find their cio_id.

You must use this value to update a person's other identifiers—their id or email, unless you enable your workspace's Allow updates to email using ID setting.

Example:person@example.com

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

You can't reference a person by their phone number here. We determine the identifier type from the shape of the value, so a phone number in the path is treated as an id. To identify people by phone number, use the Track v2 API.

Request body

idstring

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.

emailstring email

The email address of the customer.

anonymous_idstring

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.

created_atinteger

The Unix timestamp when the user was created.

_timestampinteger

The Unix timestamp for when the attribute update occurred. This can be used to control the order of attribute updates when multiple requests are sent in rapid succession.

_updateboolean

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.

unsubscribedboolean

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. We support any case of true (i.e. TRUE, true, tRUe, etc.), 1, or "1" to represent unsubscribed. Any other value is considered “false”, or subscribed.

Example request

{
  "cio_relationships": {
    "relationships": [
      {
        "identifiers": {
          "object_type_id": "1",
          "object_id": "acme"
        },
        "relationship_attributes": {
          "role": "admin"
        }
      }
    ]
  }
}

Response

A successful request returns an empty object response.

Changes

No recorded changes to this endpoint across all 1 revision of this API.