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);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

bird numbers update <number-id> \
  --name 'Support line' \
  --reference STORE-042

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

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"
      }
    ]
  }
}

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 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.

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.

Show child attributes

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.

Show child attributes

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.

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

Get an implementation brief

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

bird numbers update <number-id> \
  --name 'Support line' \
  --reference STORE-042

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

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"
      }
    ]
  }
}

Update an allocated number

Parameters

Request Payload

Response Payload

Related resources