Identify Users

The identify endpoint links user traits (such as email, name, plan, and company) to a distinct_id. Once identified, these traits appear alongside events in the Chippy Analytics dashboard, enabling segmentation and cohort analysis.

POST /api/v1/identify

Request Body

Field	Type	Required	Description
`app_id`	string	Yes	Your Chippy app identifier
`distinct_id`	string	Yes	The unique identifier for the user you are identifying
`traits`	object	Yes	Key-value pairs of user traits (at least one trait required)

Example Request

curl -X POST https://analytics.chippy.build/api/v1/identify \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "distinct_id": "user-123",
    "traits": {
      "email": "[email protected]",
      "name": "Jane Smith",
      "plan": "team",
      "company": "Acme Corp"
    }
  }'

const response = await fetch("https://analytics.chippy.build/api/v1/identify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: "your-app-id",
    distinct_id: "user-123",
    traits: {
      email: "[email protected]",
      name: "Jane Smith",
      plan: "team",
      company: "Acme Corp",
    },
  }),
});

import requests

response = requests.post(
    "https://analytics.chippy.build/api/v1/identify",
    headers={
        "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "app_id": "your-app-id",
        "distinct_id": "user-123",
        "traits": {
            "email": "[email protected]",
            "name": "Jane Smith",
            "plan": "team",
            "company": "Acme Corp",
        },
    },
)

Response

202 Accepted

{
  "success": true,
  "message": "Identity accepted"
}

Error Responses

400 Bad Request: missing traits:

{
  "error": "traits must contain at least one key-value pair"
}

401 Unauthorized: invalid API key:

{
  "error": "Invalid or expired API key"
}

Common Traits

You can send any key-value pairs as traits. The following are commonly used and have built-in support in the Chippy Analytics dashboard:

Trait	Type	Description
`email`	string	User’s email address
`name`	string	Full display name
`first_name`	string	First name
`last_name`	string	Last name
`phone`	string	Phone number
`avatar`	string	URL to the user’s avatar image
`created_at`	string	ISO 8601 timestamp of when the user account was created
`plan`	string	Current subscription plan (e.g., `free`, `solo`, `team`, `enterprise`)
`company`	string	Company or organization name
`industry`	string	Industry vertical
`role`	string	User’s role within their organization

Custom traits beyond this list are fully supported. Any key-value pair you send will be stored and available for filtering in the dashboard.

When to Call Identify

Call the identify endpoint at key moments in the user lifecycle to keep traits current:

On signup: set initial traits like email, name, plan, and created_at.
On login: refresh traits in case they changed since the last session.
When the user profile changes: update specific traits such as plan after an upgrade, or company after an org change.

You do not need to send every trait on every call. Chippy merges new traits with existing ones, so you can send only the fields that changed.

Example: Updating a single trait after a plan upgrade

curl -X POST https://analytics.chippy.build/api/v1/identify \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "distinct_id": "user-123",
    "traits": {
      "plan": "enterprise"
    }
  }'

Each identify call creates a special $identify event internally. This means you can see exactly when user traits were set or updated in your event timeline.

​Identify Users

​POST /api/v1/identify

​Request Body

​Example Request

​Response

​Error Responses

​Common Traits

​When to Call Identify

​Example: Updating a single trait after a plan upgrade

Identify Users

POST /api/v1/identify

Request Body

Example Request

Response

Error Responses

Common Traits

When to Call Identify

Example: Updating a single trait after a plan upgrade