Identify Call

The identify call tells Accoil who a user is. It creates a user profile if one does not exist, or updates it if it does. Every user in Accoil is tied to a unique identifier -- there is no anonymous tracking.

When to fire an identify call

User signs up -- immediately after account creation, before any track calls
User logs in -- ensures traits are current for the session
User profile changes -- role change, email update, subscription conversion

The goal is to ensure Accoil always has up-to-date user information before events are recorded against that user.

Required fields

Field	Type	Description
`userId`	string	A unique, stable identifier for the user. This is the primary key in Accoil.
`timestamp`	string (ISO 8601)	When this identification occurred. Defaults to current UTC time if omitted.

Anonymous users are not supported

Every identify call must include a userId. Accoil does not create user profiles from calls without a user identifier. If your application has anonymous visitors, only begin sending data after the user authenticates.

Recommended traits

Traits are optional key-value pairs that describe the user. While you can send any custom traits, these are the ones Accoil uses most effectively:

Trait	Recommendation	Type	Description
`email`	Highly recommended	string	The user's email address. Used for display and cross-platform matching.
`name`	Highly recommended	string	The user's full name. Makes user profiles human-readable in the Accoil UI.
`created_at`	Highly recommended	string (ISO 8601)	When the user first signed up. Required for accurate tenure calculations.
`role`	Recommended	string	The user's role in their account (e.g., `"admin"`, `"member"`, `"owner"`). Enables role-based segmentation.

Example payload

{
  "userId": "user_12345",
  "traits": {
    "email": "alice@acme.com",
    "name": "Alice Chen",
    "created_at": "2024-08-01T12:00:00Z",
    "role": "admin"
  },
  "timestamp": "2025-01-28T12:00:00Z"
}

cURL example (v2)

curl -X POST https://in.accoil.com/v2/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -d '{
    "userId": "user_12345",
    "traits": {
      "email": "alice@acme.com",
      "name": "Alice Chen",
      "created_at": "2024-08-01T12:00:00Z",
      "role": "admin"
    },
    "timestamp": "2025-01-28T12:00:00Z"
  }'

The API returns 202 Accepted. Processing happens asynchronously.

Optional: associating a user with an account

You can include a groupId in the identify call to associate the user with an account at the same time:

{
  "userId": "user_12345",
  "groupId": "account_67890",
  "traits": {
    "email": "alice@acme.com",
    "name": "Alice Chen"
  },
  "timestamp": "2025-01-28T12:00:00Z"
}

This is a convenience -- you can also establish the relationship with a separate group call.

Best practices

Send identify before track. Ensure the user profile exists in Accoil before recording events against it.
Use stable, immutable IDs. Use your database primary key or an internal user ID -- not an email address, which can change.
Keep traits current. Re-send identify calls when traits change. Accoil merges new traits with existing ones.
Include created_at from the start. If you omit the signup date, Accoil cannot calculate user tenure accurately.
Match IDs across platforms. If you also use HubSpot, Intercom, or Segment, use the same userId for seamless data reconciliation.

How Accoil Works -- the three-call model overview
Group Call -- linking users to accounts
Track Call -- recording events

Identify Call

On this page