Sign in
Identities

Update Identity

patch/api/v1/identities/{agent_handle}

Path parameters

agent_handlestring required

Headers

Idempotency-Keystring nullable

Required when claim_imessage_number claims a new line; replays return the original PATCH result.

Required when claim_imessage_number claims a new line; replays return the original PATCH result.

Request body

agent_handlestring nullable

New handle for the identity. A leading '@' is stripped automatically. Omit to leave unchanged.

display_namestring nullable

New human-readable display name for the identity. Omit to leave unchanged; send null to clear.

descriptionstring nullable

New free-form description of what the identity is. Omit to leave unchanged; send null to clear.

imessage_enabledboolean nullable

Whether this identity can be reached through the shared iMessage service. Omit to leave unchanged.

contact_sharing_enabledboolean nullable

Whether an attached dedicated iMessage line automatically shares this identity's name and optional avatar. Omit to leave unchanged.

imessage_number_idstring uuid nullable

Dedicated iMessage number to attach. Send a number UUID to attach or atomically swap from the current dedicated number, null to move to the shared service, or omit to leave unchanged. Available to admin-scoped API keys and JWT callers.

claim_imessage_numbertrue nullable

Claim and attach a dedicated iMessage line. Omit to avoid provisioning. Requires an Idempotency-Key header when supplied.

imessage_filter_mode'whitelist' | 'blacklist'
mail_filter_mode'whitelist' | 'blacklist'
phone_filter_mode'whitelist' | 'blacklist'

Response

Successful Response

idstring uuid required
organization_idstring required
agent_handlestring required
display_namestring nullable
descriptionstring nullable
status'active' | 'paused' | 'deleted'
imessage_enabledboolean
contact_sharing_enabledboolean
imessage_filter_mode'whitelist' | 'blacklist'
mail_filter_mode'whitelist' | 'blacklist'
phone_filter_mode'whitelist' | 'blacklist'
email_addressstring email nullable
has_avatarboolean
created_atstring date-time required
updated_atstring date-time required
signing_key_configuredboolean
signing_key_created_atstring date-time nullable

Changes