Customer.io
v1.0.0
OpenAPI 3.1.0

Add and Update People

US region

Client Libraries
Shell Curl

Add and Update People

​

Identifies a person and assigns traits to them.

In most cases, you'll identify people with a userId or an anonymousId. But when you use Customer.io as a destination, you can pass an empty userId or anonymousId, and identify people by their email trait.

When you use our libraries, you'll typically only provide an ID and traits. The libraries fill in the rest of the payload automatically.

Headers
  • X-Strict-Mode
    enum
    const:  
    1

    When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more

    values
    • 1
Body
application/json
    • userId
      Type: string
      required

      The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

    • anonymousId
      Type: string

      A unique substitute for a User ID in cases when you don’t have an absolutely unique identifier. Our libraries generate this value automatically to help you track people before they sign up, log in, provide their email, etc.

    • context

      A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

      A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

      • active
        Type: boolean

        Whether a user is active.

        This is usually used when you send an .identify() call to update the traits independently of when you've “last seen” a user.

      • campaign
        Type: object

        Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).

      • channel
        Type: string enum

        The channel the event originated from.

        values
        • browser
        • server
        • mobile
      • ip
        Type: string

        The user's IP address. This isn't captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).

      • locale
        Type: string

        The locale string for the current user, e.g. en-US.

      • page
        Type: object

        Contains information about the current page in the browser. This is automatically collected by our JavaScript source.

      • userAgent
        Type: string

        The user agent of the device making the request

    • integrations
      Type: object

      Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

    • messageId
      Type: string

      A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

    • originalTimestamp
      Type: string Format: date-time

      In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

    • sentAt
      Type: string Format: date-time

      The ISO-8601 timestamp when a library sends an event to Data Pipelines.

    • timestamp
      Type: string Format: date-time

      The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

    • traits
      Type: object

      Additional properties that you know about a person. We've listed some common/reserved traits below, but you can add any traits that you might use in another system.

Responses
  • 200

    A successful request returns an empty object response.

Request Example for post/identify
{
  "userId": "97980cfea0067",
  "traits": {
    "email": "cool.person@example.com",
    "name": "Cool Person",
    "likes_baseball": true,
    "games_attended": 5
  }
}
No Body

A successful request returns an empty object response.