Release multiple phone numbers

Server URLloading...

POST

/v1/phone-numbers/bulk/release

Send

Authorization

Query

Body

Release up to 100 assigned numbers in a single call. Each number is processed independently, so partial success is normal: the response sorts results into three buckets rather than failing the whole call. Routing is cleared for every released number before the response returns, so they stop receiving inbound webhooks and delivery receipts.

Setting ?return_to_carrier=true is rejected with 403 FORBIDDEN for every caller. This endpoint only recycles numbers back into your pool.

The three buckets are:

• released numbers that were assigned and are now recycled. Routing is cleared and the number re-enters availability after a quarantine window.
• unknown numbers that are not currently assigned to your organization, whether not found, already available, or owned by another organization. These are grouped together so ownership cannot be probed.
• already_released numbers that were already released.

There is no failed bucket. Duplicate ids are de-duplicated silently. A malformed id returns 422 VALIDATION_FAILED. The three arrays are always present (never null), and their combined length equals the number of unique ids you submitted.

Requires the numbers:write scope.

Query Parameters

Response Body

curl -X POST "https://example.com/v1/phone-numbers/bulk/release" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "11111111-1111-1111-1111-111111111111",      "22222222-2222-2222-2222-222222222222",      "33333333-3333-3333-3333-333333333333"    ]  }'

{
  "success": true,
  "data": {
    "released": [
      "11111111-1111-1111-1111-111111111111"
    ],
    "unknown": [
      "33333333-3333-3333-3333-333333333333"
    ],
    "already_released": [
      "22222222-2222-2222-2222-222222222222"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "authentication failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "return_to_carrier on bulk release is admin-only and lives on /v1/admin/inventory/return: forbidden",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "validation failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
    "details": {
      "to": "must be E.164",
      "body": "must be 1..1600 chars"
    }
  }
}