Add or update a customer

Server

US region

Client Libraries

Shell Curl

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.

Path Parameters

identifier
required

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.
Type: string · id

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

Body

application/json

The body of the request contains key-value pairs representing attributes that you want to assign to, or update for, a person.

If your request body contains "identifiers" (like id or email), your request attempts to update that person. If the identifier in the path and identifiers in the request body belong to different people, your request will produce an Attribute Update Failure.

_timestamp
Type: integer

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.
_update
Type: boolean

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.
anonymous_id
Type: string

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.
cio_relationships
Type: object

Describes relationships to an entity—a non-person object in Customer.io, like a company, educational course, job board, etc.
cio_subscription_preferences
Type: object

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>.
created_at
Type: integer

The Unix timestamp when the user was created.
email
Type: stringFormat: email

The email address of the customer.
id
Type: string

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.
unsubscribed
Type: boolean

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

Set attributes on customers. Attributes can have string, integer, or boolean values.
Type: string

Set attributes on customers. Attributes can have string, integer, or boolean values.

Responses

200

A successful request returns an empty object response.
401

Unauthorized request. Make sure that you provided the right credentials.

put/api/v1/customers/{identifier}

curl https://track.customer.io/api/v1/customers/12345 \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "email": "customer@example.com",
  "created_at": 1361205308,
  "first_name": "Bob",
  "plan": "basic",
  "cio_relationships": {
    "action": "add_relationships",
    "relationships": [
      {
        "identifiers": {
          "object_type_id": "1",
          "object_id": "01H5Q5SZVQDJ71SBME2SMDXS88"
        },
        "relationship_attributes": {
          "role": "admin"
        }
      },
      {
        "identifiers": {
          "object_type_id": "2",
          "object_id": "1171SBME"
        },
        "relationship_attributes": {
          "role": "viewer"
        }
      }
    ]
  },
  "cio_subscription_preferences": {
    "topics": {
      "topic_1": true,
      "topic_2": true,
      "topic_3": false
    }
  }
}'

No Body

A successful request returns an empty object response.

Add or update a customer

Authentication

Add or update a customer