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}/mailbox
Link 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
JSON
Response (200)
Returns the full identity detail object with the newly linked mailbox.
JSON
Error 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
cURL
Unlink mailbox DELETE
DELETE /identities/{agent_handle}/mailbox
Remove 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
cURL
Assign phone number POST
POST /identities/{agent_handle}/phone_number
Link 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
JSON
Response (200)
Returns the full identity detail object with the newly linked phone number.
JSON
Error 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
cURL
Unlink phone number DELETE
DELETE /identities/{agent_handle}/phone_number
Remove 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.
JSON
cURL