Identify

POST /agent/identify

Upserts who the app's current user is — a name and a handful of free-form identifiers — so that if the conversation is escalated to a human, your support queue can show a real person instead of an opaque session id.

Auth: required.

This endpoint is write-only and scoped to the calling project: it can only upsert the user the request claims to be. It cannot read, list, or delete the identity registry — that's a dashboard-only capability. See Dashboard: Projects & API keys and the rest of the Dashboard section for operator-side user management.

Body

Field	Type	Required	Description
userId	string	Yes	Your identifier for the user.
name	string	No	Display name to show in escalation/operator tooling.
identifiers	object (Record<string, string>)	No	Free-form lookup keys, e.g. email, phone. Keep this to a handful of fields.

A request that fails body validation (e.g. missing userId) returns 422 with error.code: "VALIDATION_ERROR".

Response — 200

{
  "success": true,
  "data": { "identified": true }
}

Privacy

User identifiers are never sent to the model.

curl

curl https://api.appilots.com/api/v1/agent/identify \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "name": "Jordan Lee",
    "identifiers": { "email": "jordan@example.com" }
  }'

TypeScript

const res = await fetch("https://api.appilots.com/api/v1/agent/identify", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_xxxxxxxxxxxx...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "user_123",
    name: "Jordan Lee",
    identifiers: { email: "jordan@example.com" },
  }),
});
const { data } = await res.json();

Related pages

• Sessions & Users — how identified users relate to sessions
• Escalations — where identified user info shows up for operators