Users - HaloAgents

Endpoint

POST /api/sdk/users/identify

Upsert an end user record and optionally link them to an existing session. Called automatically when you use identify() in the SDK, but you can also call it directly from your backend.

Backfilling or importing existing users? Every identify call bumps the user’s last_seen to now, so looping it over your user base marks everyone “active today” and corrupts activity data. Use Update / Backfill Users instead, which never touches activity timestamps. See Importing & Backfilling Data.

Authentication

Requires your publishable widget key in the Authorization header:

Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx

The org_id is derived from the widget key. You do not need to pass it in the request body.

Request Body

string

required

Your system’s unique identifier for this user.

object

User attributes. Recognized fields (name, email, signed_up_at, renewal_date, renewal_status, contract_term, payment_terms, on_contract, mrr, arr) are stored in dedicated columns. All other fields are stored in custom_fields. See User Traits for recommended fields.Do not send id, external_id, org_id, company_id, created_at, updated_at, first_seen, last_seen, or last_contacted_at. These are managed by Halo and the endpoint returns HTTP 400 if any of them appear in the body. Use signed_up_at to set the date the user signed up in your product. See System-managed fields.

object

Structured context entries for AI consumption. Stored in the context jsonb column. Merged with existing context (new keys overwrite). See Context Entries.

string

If provided, any orphaned transcripts or tickets from this session (created before the user was identified) are retroactively linked to the user record.

string

JWT signed with your Identity Secret (HS256). Required when identity verification is enabled for your workspace. The token’s user_id claim must match the user_id field. If the token carries email or name claims and the traits body omits those fields, the verified claim values are stored on the user record. See Identity Verification.

Recognized Traits

These trait keys are stored in dedicated database columns for filtering and display:

Key	Type	Description
`name`	string	User’s display name
`email`	string	User’s email address
`signed_up_at`	string	ISO 8601 date the user signed up in your product. Populates the dedicated `end_users.signed_up_at` column.
`mrr`	number	Monthly recurring revenue in cents (only when MRR mode is “manual” or Stripe is not connected)
`arr`	number	Annual recurring revenue in cents (same conditions as MRR)
`renewal_date`	string	ISO 8601 date for contract renewal
`contract_term`	string	One of: `monthly`, `quarterly`, `annual`, `bi_annual`
`payment_terms`	string	One of: `monthly`, `quarterly`, `annual`, `bi_annual`
`on_contract`	boolean	Whether the user is on a contract
`renewal_status`	string	One of: `up_for_renewal`, `in_progress`, `likely_to_renew`, `expansion_opportunity`, `set_to_cancel`, `at_risk`, `renewed`, `lost`

All other trait keys are stored as custom fields and are accessible to the AI agent.

Rejected Traits

These keys trigger HTTP 400 if present in the traits body. They are managed by Halo and customer-set values would silently shadow the real columns. See System-managed fields for context.

Key	Why
`id`	Halo’s internal primary key. Pass your identifier as `user_id` instead.
`external_id`	Halo’s mirror of the `user_id` you sent. Use `user_id` at the top level.
`org_id`	Set by Halo from the API key.
`company_id`	Set by Halo when you call `/api/sdk/companies/identify`. Don’t override here.
`created_at`	Halo sets this when the row is inserted. Pass `signed_up_at` if you want to record customer signup.
`updated_at`	Maintained automatically by a database trigger.
`first_seen`	Maintained by Halo (first time we observed any activity from the user).
`last_seen`	Bumped by every identify, event, and message.
`last_contacted_at`	Set when your team sends a broadcast, series, reply, or chat.

Example

curl -X POST https://api.haloagents.ai/api/sdk/users/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "traits": {
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "role": "admin",
      "plan": "enterprise",
      "department": "Engineering"
    },
    "context": {
      "recent_activity": {
        "label": "Recent Activity",
        "type": "list",
        "value": [
          { "name": "Created API key", "timestamp": "2026-03-15T10:00:00Z" },
          { "name": "Enabled SSO", "timestamp": "2026-03-14T15:30:00Z" }
        ]
      }
    }
  }'

const response = await fetch(
  "https://api.haloagents.ai/api/sdk/users/identify",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer ab_live_xxxxxxxxxxxxxxxx",
    },
    body: JSON.stringify({
      user_id: "user_123",
      traits: {
        name: "Jane Doe",
        email: "jane@acme.com",
        role: "admin",
        plan: "enterprise",
        department: "Engineering",
      },
      context: {
        recent_activity: {
          label: "Recent Activity",
          type: "list",
          value: [
            { name: "Created API key", timestamp: "2026-03-15T10:00:00Z" },
            { name: "Enabled SSO", timestamp: "2026-03-14T15:30:00Z" },
          ],
        },
      },
    }),
  }
);

const data = await response.json();
console.log(data.user.id);

import requests

response = requests.post(
    "https://api.haloagents.ai/api/sdk/users/identify",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer ab_live_xxxxxxxxxxxxxxxx",
    },
    json={
        "user_id": "user_123",
        "traits": {
            "name": "Jane Doe",
            "email": "jane@acme.com",
            "role": "admin",
            "plan": "enterprise",
            "department": "Engineering",
        },
    },
)

data = response.json()
print(data["user"]["id"])

Response:

{
  "user": {
    "id": "uuid",
    "org_id": "your-org-id",
    "external_id": "user_123",
    "first_seen": "2026-01-15T08:00:00.123456+00:00",
    "last_seen": "2026-03-15T10:30:00.789012+00:00",
    "signed_up_at": null,
    "created_at": "2026-01-15T08:00:00.123456+00:00",
    "updated_at": "2026-03-15T10:30:00.789012+00:00"
  }
}

The response is a minimal projection of the stored record. Traits, context, custom fields, email, name, revenue, and score fields are not echoed back, because this endpoint is callable with the public widget key. Read full contact data through the dashboard or MCP instead. All timestamps in the response are Postgres timestamptz values serialized as ISO 8601 with microsecond precision and a +00:00 offset.

created_at, updated_at, first_seen, and last_seen are read-only Halo-managed timestamps. Do not echo them back into the traits body on subsequent calls (the endpoint returns HTTP 400 if you do).
signed_up_at is customer-writable via traits.signed_up_at on a follow-up identify call. On update the column uses COALESCE semantics, so passing null (or omitting the key) preserves the existing value. Pass a new ISO 8601 string to overwrite.

Behavior

If a user with the same user_id exists within your organization, it is updated
If it doesn’t exist, it is created
Traits are merged: existing values are preserved, matching keys are overwritten
Context is merged: existing keys are preserved, new keys are added, matching keys are overwritten
The combined size of traits and context must not exceed 20,000 bytes
When session_id is provided, orphaned transcripts and tickets from that session are retroactively linked to the user
An unverified traits.email that already belongs to another contact in your workspace is not used to link or merge into that contact. The user keeps their own record and the address is stored in custom_fields.email. To link a user to an existing contact by email, send a user_token whose verified email claim matches

​Endpoint

​Authentication

​Request Body

​Recognized Traits

​Rejected Traits

​Example

​Behavior

Endpoint

Authentication

Request Body

Recognized Traits

Rejected Traits

Example

Behavior