Cancel a dedicated number
/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);# A billed number stays yours until its paid period ends, then is released;
# releases_at says when. One with no subscription is released now.
allocated = client.numbers.cancel("nda_01krdgeqcxet5s7t44vh8rt9mg")
print(allocated.releases_at)// A billed number stays yours until its paid period ends, then is released;
// releases_at says when. One with no subscription is released now.
allocated, err := client.Numbers.Cancel(context.Background(), "nda_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
log.Fatal(err)
}
fmt.Println(allocated.ReleasesAt)// A billed number stays yours until its paid period ends, then is released;
// releases_at says when. One with no subscription is released now.
$allocated = $bird->numbers->cancel('nda_01krdgeqcxet5s7t44vh8rt9mg');
echo $allocated->getReleasesAt()?->format(DATE_ATOM), "\n";bird numbers cancel <number-id> --yescurl -X DELETE "https://us1.platform.bird.com/v1/numbers/{number_id}" \
-H "Authorization: Bearer $TOKEN"{
"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.
Parameters
number_idstringIdentifier of the number to cancel, as returned in the id field of GET /v1/numbers.
Response Payload
nameThe name you gave this number in your workspace. Null when no name is set.
referenceYour own reference for this number in your workspace. Null when no reference is set.
idIdentifier of this allocated number. Pass it as number_id to read this number, or to cancel or release it when kind is dedicated.
kindHow 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
numberPhone number in E.164 format.
country_codenumber_typePhysical type of this phone number.
capabilitiesCapabilities supported by this number.
statusThe allocation and ownership-approval status of this number.
activemeans this number is allocated to your workspace and usable.pending_ownership_registrationmeans 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. Readownership.statusandownership.nextfor the current decision and remaining work.releasedmeans 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_atWhen this number was allocated to your workspace.
releases_atWhen 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_atWhen this number was released. null while it is still allocated to your workspace.
ownershipOwnership 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.
Onderliggende attributen tonen
ownership.submission_idThe 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.satisfiedWhether 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.statusCurrent ownership registration approval status. Operational activation is separate:
blocked_at records the ownership block on number use, and next describes remaining work.
needs_inputmeans ownership details or a submission correction are needed.under_reviewmeans your current answers are being reviewed.approval_pendingmeans your paperwork is accepted but registration approval is still pending.approvedmeans ownership registration is approved. Number activation can still be pending whileblocked_atis non-null.not_requiredmeans no active ownership requirement applies, including after a requirement is withdrawn.rejectedmeans the submission was closed or the verifier correction deadline passed. Corrections are no longer accepted for this submission.unknownmeans current approval status could not be determined. Readblocked_atfor any recorded ownership block. Retry the read.
Possible values: needs_input, under_review, approval_pending, approved, not_required, rejected, unknown
ownership.blocked_atWhen 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.nextActions 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.
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.