Jump to

Manage Identities

Agent identities are org-scoped and identified by a unique agent_handle. Handles are normalized — a leading @ is automatically stripped, so @my-agent and my-agent are equivalent.

Create identity POST

POST /identities

Create a new agent identity. The handle must be unique within your organization.

Request body

Field	Type	Required	Description
`agent_handle`	string	Yes	Unique handle for the identity. 1–255 chars. Leading `@` is stripped.

Request example

JSON

Response (201)

JSON

Error responses

Status	Description
403	Organization ID missing from token
409	Handle already taken within the organization

Code examples

List identities GET

GET /identities

List all active identities for your organization, newest first.

Response (200)

JSON

Code examples

Get identity GET

GET /identities/{agent_handle}

Get a single identity with its linked communication channels (mailbox and phone number). This is the only endpoint that returns the full detail response with nested channel objects.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Handle of the identity (leading `@` is stripped)

Response (200)

JSON

If no mailbox or phone number is assigned, those fields are null.

Error responses

Status	Description
403	Organization ID missing from token
404	Identity not found or deleted

Code examples

Update identity PATCH

PATCH /identities/{agent_handle}

Update an identity's handle or status. Only supplied fields are modified.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Current handle of the identity to update

Request body

Field	Type	Required	Description
`agent_handle`	string	No	New handle. 1–255 chars. Leading `@` is stripped.
`status`	string	No	New status: `active` or `paused`

Request example

JSON

Response (200)

JSON

Error responses

Status	Description
400	Invalid status value
403	Organization ID missing from token
404	Identity not found or deleted
409	New handle already taken within the organization

Code examples

Delete identity DELETE

DELETE /identities/{agent_handle}

Delete an identity. Any assigned mailbox or phone number is unlinked (but not deleted — they remain available for reassignment). Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Handle of the identity to delete

Code examples

Identity object

Field	Type	Description
`id`	UUID	Unique identity identifier
`organization_id`	string	Organization that owns this identity
`agent_handle`	string	Unique handle within the organization
`status`	string	Lifecycle status: `active`, `paused`, `deleted`
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Identity detail object

Extends the identity object with linked channel data. Returned by the get and channel assignment endpoints.

Field	Type	Description
...all identity fields
`mailbox`	object \| null	Linked mailbox object, or `null` if unassigned
`phone_number`	object \| null	Linked phone number object, or `null` if unassigned