Release a phone number back to the pool

Releases an owned number back to the carrier pool and stops its monthly billing.

Endpoint

DELETE https://api.dairo.app/v1/phone/numbers/{id}

Releases an owned number back to the carrier pool and stops its monthly billing. This is irreversible — once released the number can be bought by anyone, and any agent identity built on it is gone — so the request must include confirm: true or it returns a 400. The row is soft-deleted: it is retained for the audit trail with status: "released" and a releasedAt timestamp, and is hidden from the numbers list unless you pass includeReleased=true. Releasing a number that is already released returns 409. Requires the phone:write scope.

Scope: phone:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X DELETE "https://api.dairo.app/v1/phone/numbers/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true
  }'

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes	The phone number's ID.

Body

Required, application/json: PhoneNumberReleaseRequest.

Field	Type	Required	Description
`confirm`	`true`	yes	Releasing is irreversible: the number returns to the public pool.

Response

200 Success. Body: application/json, PhoneNumber.

Field	Type	Required	Description
`object`	`"phone_number"`	yes
`id`	string (uuid)	yes
`phoneNumber`	string	yes	E.164.
`countryCode`	string	yes
`numberType`	`"local"`, `"toll_free"`, `"national"`, `"mobile"`	yes
`capabilities`	array of string	no
`status`	`"pending"`, `"active"`, `"releasing"`, `"released"`, `"failed"`	yes	`pending` means the provider reserved the number but regulatory documents are still outstanding (common for German local numbers). It is not an error.
`inboxId`	string (uuid) or null	no	When set, every inbound call to this number (summary, the caller's notes and the transcript) lands in that inbox as a `channel: "voice"` message.
`agentId`	string (uuid) or null	no
`inboundInstructions`	string or null	no	Who the inbound agent is and what the line is for. null = the default assistant that takes messages and notes. (max length 8000)
`inboundGreeting`	string or null	no	Opening line for inbound calls. null = a short default greeting (by first name for a known contact). (max length 500)
`inboundVoice`	`"marin"`, `"cedar"`, `"alloy"`, `"ash"`, `"ballad"`, `"coral"`, `"echo"`, `"sage"`, `"shimmer"`, `"verse"`, `"quartz"`, `"ripple"`, `"vesper"`, `"willow"`, `"stone"`, `"gleam"`, `"meridian"`, `"bossa"`, `"tempo"`, `"beacon"`, `"delta"`, `"cinder"`, `null`	no	Dairo Live voice id for the inbound agent.
`inboundLanguage`	string or null	no	ISO language code the inbound agent speaks.
`monthlyCostUsd`	number or null	no
`setupCostUsd`	number or null	no
`requirements`	object	no	Outstanding regulatory requirements, when `status` is `pending`.
`metadata`	object	no
`purchasedAt`	string (date-time) or null	no
`releasedAt`	string (date-time) or null	no
`createdAt`	string (date-time)	yes

200

{
  "object": "phone_number",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phoneNumber": "string",
  "countryCode": "string",
  "numberType": "local",
  "capabilities": [
    "string"
  ],
  "status": "pending",
  "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "inboundInstructions": null,
  "inboundGreeting": null,
  "inboundVoice": "marin",
  "inboundLanguage": null,
  "monthlyCostUsd": null,
  "setupCostUsd": null,
  "requirements": {},
  "metadata": {},
  "purchasedAt": "2026-10-19T09:30:00Z",
  "releasedAt": "2026-10-19T09:30:00Z",
  "createdAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`409`	The resource already exists or its state does not allow this (`duplicate_resource` or a condition-specific code).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).