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.

Release phone number

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

Parameter	Type	Description
`agent_handle`	string	Handle of the identity whose number is being released

Error responses

Status	Description
403	Organization ID missing from token
404	Identity not found
502	Carrier release failed — retry shortly

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/identities/sales-agent/phone_number" \
  -H "X-API-Key: YOUR_API_KEY"

const handle = "sales-agent";
await fetch(
  `https://inkbox.ai/api/v1/identities/${handle}/phone_number`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

handle = "sales-agent"
requests.delete(
    f"https://inkbox.ai/api/v1/identities/{handle}/phone_number",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Release Phone Number