Accoil HomeAccoil Docs
Guides
Accoil App

Identify Call

Identify Calls are used to recognize individual users and associate their actions with specific traits. These calls help you build detailed user profiles that provide insights into behavior, segmentation, and engagement.

Suggest Edits

Overview

The Identify Call links user activity to a unique identifier (user_id) and allows you to assign traits to that user. Traits are static pieces of information, such as email, name, or role, that provide context about the user.

📘

Anonymous users are not supported

Accoil does not support tracking anonymous users. You must include a unique user_id with every Identify Call to associate actions with a specific user.

When to Use Identify Calls

You should make an Identify Call:

  1. When a user is created: Send an Identify Call immediately after a user signs up.
  2. On significant user updates: Use an Identify Call whenever a user’s traits change, such as:
    • Conversion from trial to paid.
    • Upgrades or downgrades in subscription.
    • Updates to their role or profile information (e.g., name, location).
  3. At login or session start: To ensure all subsequent Track Calls are associated with the correct user.

Recommended User Traits

Here are the traits we recommend sending with every Identify Call:

TraitRecommendationDescription
emailHighly RecommendedThe user’s email address. Often used as a universal identifier across platforms.
nameHighly RecommendedThe user’s full name. Used for a more personalized interface in Accoil.
created_atHighly RecommendedThe user’s signup date (ISO 8601 or Unix timestamp). Ensures tenure tracking is accurate.
roleRecommendedThe user’s role in the account (e.g., Admin, Owner, Team Member). Helps segment users by type.

Example Identify Call

Here’s an example of an Identify Call: 

{
  "user_id": "user_12345",
  "traits": {
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-08-01",
    "role": "Admin"
  },
  "timestamp": "2025-01-28T12:00:00Z"
}

Required Fields

Here are the fields required in every Identify Call:

  • user_id: (String) A unique identifier for the user. This is mandatory to link user actions to a profile. Anonymous users are not supported.
  • timestamp: (String) The ISO 8601 or Unix timestamp of when the Identify Call was made.

Optional Fields

  • traits: (Object) Key-value pairs describing user attributes, such as:
    • email (e.g., "user@example.com")
    • name (e.g., "John Doe")
    • role (e.g., "Admin")
      These traits provide additional context about the user but are not required for the Identify Call.

Best Practices for Identify Calls

  1. Always Include user_id
    A unique user_id is mandatory. Without it, Accoil cannot associate actions with a user, and anonymous tracking is not supported.

  2. Use Consistent Timestamps
    Include a valid ISO 8601 or Unix timestamp to ensure chronological accuracy in your analytics.

  3. Add Traits to Enrich User Profiles (Optional)
    While not required, sending traits allows you to create richer user profiles. For example, tracking a user’s role, email, or created_at date can provide better insights into user behavior.

  4. Update Traits When Necessary
    Make additional Identify Calls whenever important user information changes, such as:

    1. Subscription upgrades or downgrades.
    2. A new email address or updated profile details.

Updated 25 days ago