Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Update an allocated number

PATCH
/v1/numbers/{number_id}
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
Response200
{
  "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"
      }
    ]
  },
  "pricing": {
    "recurring_price": {
      "amount": "0.00995",
      "currency_code": "USD"
    },
    "recurring_period": {
      "unit": "month",
      "count": 1
    },
    "intervals_per_charge": 12,
    "error": null
  }
}

Updates the name and reference for a number allocated to your workspace. Omit a field to keep its current value, or send null to clear it. Leading and trailing whitespace is removed. References need not be unique.

Parameters

number_idstring

Identifier returned by the allocated-number list.

Request Payload

name
nullable string

A name for this number in your workspace, such as Support line. Send null to clear it, or omit it to keep the current name.

reference
nullable string

Your own reference for this number, such as an identifier from your records. References need not be unique. Send null to clear it, or omit it to keep the current reference.

Response Payload

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 cancel or 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

ISO 3166-1 alpha-2 country code.

number_type
string
required

Physical type of this phone number.

Possible values (may grow over time): mobile, local, national, short_code, short_code_fteu, toll_free

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
required

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.

Show child attributes
pricing
nullable object
required

What your organization pays for this number. null for a shared number, and, when the price was read, for a number with no live subscription. Otherwise its prices are null when no price applies. When the price could not be read, every dedicated number carries this object with error set, whether or not it has a live subscription.

Show child attributes
pricing.recurring_price
nullable object
required

What your organization is charged for this number per recurring_period, net of tax, in the currency this number is charged in: your billing currency, unless this number's subscription predates a change of your billing currency, in which case its own currency is returned. null when no price applies.

Show child attributes
pricing.recurring_period
nullable object
required

The rate's interval, or a fixed price's whole renewal period. null when recurring_price is null.

Show child attributes
pricing.intervals_per_charge
nullable integer
required

How many recurring_periods one renewal charges. When releases_at is set no renewal follows, and the value still describes the subscription's cadence until the release. 1 for a fixed price. null when recurring_price is null.

pricing.error
nullable object
required

A retryable failure to read the price. Retry a GET of the number; do not repeat a completed write. null when the price was read or no price applies.

Show child attributes

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief