Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Cancel a dedicated number

DELETE
/v1/numbers/{number_id}
// A billed number stays yours until its paid period ends, then is released;
// releases_at says when. One with no subscription is released now.
const allocated = await bird.numbers.cancel("nda_01krdgeqcxet5s7t44vh8rt9mg");
console.log(allocated.releases_at);
Réponse200
{
  "id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "kind": "dedicated",
  "number": "+12025550123",
  "name": "Support line",
  "reference": "CUST-778812",
  "country_code": "US",
  "number_type": "local",
  "capabilities": [
    "sms",
    "voice"
  ],
  "status": "released",
  "allocated_at": "2026-08-19T10:00:00Z",
  "releases_at": null,
  "released_at": "2026-10-06T14:02:11Z",
  "ownership": null
}

Cancels one of your workspace's dedicated numbers at the end of its current billing period. The number is not charged for another period, keeps its current status until the period ends, and is then released. The 202 response returns the number with releases_at set to that time, and cancelling a number that is already scheduled returns the same schedule. A number with no subscription behind it, such as one allocated to you without a charge, is released immediately and answers 200 with the number as released. While a renewal payment for the number is overdue, the request answers 409 until it is paid. To release a number now, use POST /v1/numbers/{number_id}/release. Shared numbers belong to Bird-managed shared infrastructure and cannot be cancelled from your workspace.

Paramètres

number_idstring

Identifier of the number to cancel, as returned in the id field of GET /v1/numbers.

Contenu de la réponse

name
nullable string
obligatoire

The name you gave this number in your workspace. Null when no name is set.

reference
nullable string
obligatoire

Your own reference for this number in your workspace. Null when no reference is set.

id
string
obligatoire

Identifier of this allocated number. Pass it as number_id to read this number, or to cancel or release it when kind is dedicated.

kind
string
obligatoire

How this number is allocated. dedicated belongs to your workspace and is billed as a subscription. shared is provided through Bird-managed shared infrastructure and is not owned or billed as a workspace subscription.

Possible values: dedicated, shared

number
string
obligatoire

Phone number in E.164 format.

country_code
string
obligatoire
number_type
string
obligatoire

Physical type of this phone number.

capabilities
array of string
obligatoire

Capabilities supported by this number.

status
string
obligatoire

The allocation and ownership-approval status of this number.

  • active means this number is allocated to your workspace and usable.
  • pending_ownership_registration means this number is allocated to your workspace and billed, but outbound SMS and both inbound and outbound voice calls are blocked until ownership registration is approved and activation completes, or the ownership requirement is withdrawn. This ownership status does not gate inbound SMS or WhatsApp. Read ownership.status and ownership.next for the current decision and remaining work.
  • released means this number is no longer allocated to your workspace.

An allocated number is not always enough to send from it: some destination countries also require an approved registration for the sender.

Possible values: active, pending_ownership_registration, released

allocated_at
string
obligatoire

When this number was allocated to your workspace.

releases_at
nullable string
obligatoire

When a scheduled release of this number takes effect, at the end of its current billing period. The number stays allocated, with its current status, until then. null when no release is scheduled.

released_at
nullable string
obligatoire

When this number was released. null while it is still allocated to your workspace.

ownership
nullable object

Ownership paperwork and activation progress. null when no ownership requirements, recorded block, or recorded decision apply, or when requirements or progress cannot be read and no ownership block or decision has been recorded. A recorded block still returns an ownership object with status: unknown when progress cannot be read; retry the read. We manage the paperwork for shared short codes, so this field is always null for them. Other sending requirements can apply even when ownership registration is complete.

Afficher les attributs enfants

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation