Release Phone Number

The mailbox and tunnel are atomic with identity create/delete — both are provisioned when you create an identity and removed when you delete it. A phone number is provisioned either alongside the identity (the optional nested phone_number payload on Create identity) or later on an existing identity via Provision phone number with agent_handle. Once attached, the number stays bound to that identity for its lifetime. Each identity supports at most one phone number, and that number is dedicated to that identity — there is no reassignment between identities.

To release a phone number, either delete the identity (the linked number is released as part of the cascade), or use the endpoint below to release the number while keeping the identity active.

DELETE /identities/{agent_handle}/phone_number

Release the identity's phone number. The number is returned to the carrier and removed from your account — it is not available for reassignment afterwards. The identity itself stays active. Returns 204 No Content on success.

Path parameters

Error responses

Code examples

cURL

cURL

JavaScript

Python