Jump to
Channel Assignment
Link communication channels to an agent identity so your agent can send email and make calls under a single handle. Each identity supports one mailbox and one phone number. A channel can only be assigned to one identity at a time.
Assign mailbox POST
POST /identities/{agent_handle}/mailboxLink a mailbox to an identity. The mailbox must belong to the same organization and must not already be assigned to a different identity.
Path parameters
| Parameter | Type | Description |
|---|---|---|
agent_handle | string | Handle of the identity to assign to |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
mailbox_id | UUID | Yes | ID of the mailbox to assign |
Request example
JSONResponse (200)
Returns the full identity detail object with the newly linked mailbox.
JSONError responses
| Status | Description |
|---|---|
| 403 | Organization ID missing from token |
| 404 | Identity or mailbox not found |
| 409 | Mailbox is already assigned to another identity |
| 422 | Missing or malformed mailbox_id |
Code examples
cURLUnlink mailbox DELETE
DELETE /identities/{agent_handle}/mailboxRemove the mailbox from an identity. The mailbox itself is not deleted — it remains available for reassignment to another identity. Returns 204 No Content on success.
Path parameters
| Parameter | Type | Description |
|---|---|---|
agent_handle | string | Handle of the identity to unlink from |
Code examples
cURLAssign phone number POST
POST /identities/{agent_handle}/phone_numberLink a phone number to an identity. The phone number must belong to the same organization and must not already be assigned to a different identity.
Path parameters
| Parameter | Type | Description |
|---|---|---|
agent_handle | string | Handle of the identity to assign to |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
phone_number_id | UUID | Yes | ID of the phone number to assign |
Request example
JSONResponse (200)
Returns the full identity detail object with the newly linked phone number.
JSONError responses
| Status | Description |
|---|---|
| 403 | Organization ID missing from token |
| 404 | Identity or phone number not found |
| 409 | Phone number is already assigned to another identity |
| 422 | Missing or malformed phone_number_id |
Code examples
cURLUnlink phone number DELETE
DELETE /identities/{agent_handle}/phone_numberRemove the phone number from an identity. The phone number itself is not deleted — it remains available for reassignment to another identity. Returns 204 No Content on success.
Path parameters
| Parameter | Type | Description |
|---|---|---|
agent_handle | string | Handle of the identity to unlink from |
Code examples
cURL