Identify

5 min

Identify calls associate a user with a set of traits. Where a track event records something that happened at a point in time, an identify records who someone is — it upserts the user profile rather than appending to their event history.

Identify calls are not counted as events, carry no event timestamp, and cannot be used to trigger downstream automation. When you need both — for example on account creation — send an identify to establish the profile and a track event such as User Created to mark the occurrence.

All identify calls must include the following properties in the payload:

Property	Type	Required?	Description
type	string	Required	identify
userId	string	Required	ID # of the identified user (or email address)
traits	object	Required	User traits to set on the profile
anonymousId	string	Optional	ID # of the unidentified user, if available. Include it to merge a known browser session into the identified profile.

Traits

traits accepts the standard trait schema documented in The Context object. At minimum, send email — it is the primary identifier most destinations use for matching.

The canonical trait names are first_name and last_name. Addresses use address1, address2, and zipcode; the legacy names street, street2, zip, and postalCode are still recognised as fallbacks but should not be used in new integrations.

Server-side traits are not optional. No context is added automatically to server-to-server events, so an identify call is the only way traits reach a server-side user profile. A track event sent without a preceding identify carries no email, phone, or address, and destinations that match on those fields will be unable to resolve the user.

Example

curl -X POST https://production.cdp.ingest.chord.co/api/s/s2s/identify \
  -H 'Content-Type: application/json' \
  -H 'X-Write-Key: <server-side-write-key>' \
  -d '{
    "type": "identify",
    "userId": "8",
    "traits": {
      "email": "[email protected]",
      "phone": "+12145550100",
      "first_name": "Jane",
      "last_name": "Doe",
      "address": {
        "address1": "Test Ln",
        "city": "New York",
        "state": "NY",
        "zipcode": "10001",
        "country": "US"
      }
    }
  }'

A successful call returns 200 {"ok":"ok"}. A 403 means the write key is missing or invalid.

When to Send an Identify

On account creation. Send the identify first to establish the profile, then send a User Created track event to record the signup. The identify makes the user addressable; the track event is what reporting counts and what downstream automation triggers on.

On profile changes. Any update to email, phone, name, or address should be forwarded so the profile stays current.

On first identification of a known session. Include anonymousId alongside userId so activity already attributed to the anonymous visitor is merged into the identified profile. Without it, a customer's browsing history and their orders remain two unrelated records.

Do not call identify from a generic persistence hook. Backends commonly save the customer record on login, cart update, and administrative edit. Forwarding all of those produces a high volume of identical identify calls and constant churn on downstream profiles. Send an identify only when a trait you actually forward has changed.

Ordering

Send the identify before any track event that depends on its traits. Traits are applied to the profile at ingest and are available to subsequent events — they are not applied retroactively to events that have already been processed.

For a server-side flow that both creates a user and records the signup, that means two sequential calls:

POST /api/s/s2s/identify   →  userId + traits
POST /api/s/s2s/track      →  event: "User Created"