---
title: "Cancel a dedicated number"
canonical: "https://bird.com/docs/api/reference/cancel-workspace-number"
---

# Cancel a dedicated number

`DELETE /v1/numbers/{number_id}`

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.

## Code samples

**TypeScript**

```ts
// 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);
```

Examples: [TypeScript](/docs/api/reference/cancel-workspace-number.ts.md) · [Python](/docs/api/reference/cancel-workspace-number.py.md) · [Go](/docs/api/reference/cancel-workspace-number.go.md) · [PHP](/docs/api/reference/cancel-workspace-number.php.md) · [CLI](/docs/api/reference/cancel-workspace-number.cli.md) · [MCP](/docs/api/reference/cancel-workspace-number.mcp.md) · [cURL](/docs/api/reference/cancel-workspace-number.curl.md)

## Example response `200`

```json
{
  "id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "kind": "dedicated",
  "country_code": "US",
  "number_type": "mobile",
  "capabilities": [
    "sms"
  ],
  "status": "active",
  "ownership": {
    "submission_id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
    "status": "needs_input",
    "next": [
      {
        "kind": "operation"
      }
    ]
  }
}
```

## Path parameters

- `number_id` (string): Identifier of the number to cancel, as returned in the id field of GET /v1/numbers.

## Response body

- `name` (nullable string, required): The name you gave this number in your workspace. Null when no name is set.
- `reference` (nullable string, required): Your own reference for this number in your workspace. Null when no reference is set.
- `id` (string, required): Identifier of this allocated number. Pass it as `number_id` to read this number, or to release it when kind is dedicated.
- `kind` (string, required)

  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, required): Phone number in E.164 format.
- `country_code` (string, required)
- `number_type` (string, required): Physical type of this phone number.
- `capabilities` (array of string, required): Capabilities supported by this number.
- `status` (string, required)

  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, required): When this number was allocated to your workspace.
- `releases_at` (nullable string, required): 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): 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.
- `ownership.submission_id` (string): The most recent ownership submission for this number, including after approval. Users with compliance read access can view the filed answers and their review status from the number's details in the dashboard. This may be a newer filing than the one that cleared the number for use. Absent when no submission was found or submission progress could not be read.
- `ownership.satisfied` (boolean, required): Whether the ownership paperwork is accepted or is no longer required. This can remain true while an external verifier asks for a correction or activation is pending. Read `status` and `next` for the current step, and `blocked_at` for the ownership block on outbound SMS and inbound and outbound voice.
- `ownership.status` (string, required)

  Current ownership registration approval status. Operational activation is separate:
  `blocked_at` records the ownership block on number use, and `next` describes remaining work.

  - `needs_input` means ownership details or a submission correction are needed.
  - `under_review` means your current answers are being reviewed.
  - `approval_pending` means your paperwork is accepted but registration approval is still pending.
  - `approved` means ownership registration is approved. Number activation can still be pending while `blocked_at` is non-null.
  - `not_required` means no active ownership requirement applies, including after a requirement is withdrawn.
  - `rejected` means the submission was closed or the verifier correction deadline passed. Corrections are no longer accepted for this submission.
  - `unknown` means current approval status could not be determined. Read `blocked_at` for any recorded ownership block. Retry the read.

  Possible values: `needs_input`, `under_review`, `approval_pending`, `approved`, `not_required`, `rejected`, `unknown`
- `ownership.blocked_at` (nullable string): When ownership requirements began blocking outbound SMS and inbound and outbound voice calls. Null when that block is clear. Accepted paperwork can still await activation with a block in place. A number bought before ownership requirements were introduced can have outstanding paperwork without a block.
- `ownership.next` (array of object, required): Actions that advance ownership registration or activation, in order. Empty when neither needs further action. A `wait` step means no customer action is needed now, including while accepted paperwork awaits activation. Read this list again after each change.
- `ownership.next.kind` (string, required)

  What you do about this step.

  - `operation`: call the operation named in `operation`, then
    read again.
  - `external`: act somewhere this API does not reach, then read
    again.
  - `wait`: nothing is asked of you, so read again later.
  - `terminal`: nothing you do resolves this, so stop retrying.

  Tolerate a value you do not recognize: show the `description` and
  offer no action.

  Possible values (may grow over time): `operation`, `external`, `wait`, `terminal`
- `ownership.next.description` (string, required): A short, human-readable label for the step, suitable for display.
- `ownership.next.operation` (string): The operationId to call. Present only when `kind` is `operation`. The operation's own schema says how to call it; this says only which one, and what to address it with.
- `ownership.next.params` (object): The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.
- `ownership.next.url` (string): A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)