Get an allocated number

GET

/v1/numbers/{number_id}

const allocated = await bird.numbers.get("nda_01krdgeqcxet5s7t44vh8rt9mg");
// A country that asks for ownership paperwork answers here; most answer null.
console.log(allocated.status, allocated.ownership ?? "no paperwork required");

allocated = client.numbers.get("nda_01krdgeqcxet5s7t44vh8rt9mg")
# A country that asks for ownership paperwork answers here; most answer None.
print(allocated.status, allocated.ownership or "no paperwork required")

allocated, err := client.Numbers.Get(context.Background(), "nda_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
// A country that asks for ownership paperwork answers on Ownership; most
// answer nil.
fmt.Println(allocated.Status)

$allocated = $bird->numbers->get('nda_01krdgeqcxet5s7t44vh8rt9mg');
// A country that asks for ownership paperwork answers here; most answer null.
echo $allocated->getStatus(), "\n";

bird numbers get <number-id>

curl -X GET "https://us1.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN"

Respuesta200

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

Returns a single phone number allocated to your workspace, whether it is a dedicated number you bought or a shared number managed for you. Numbers you have released are no longer returned. An allocated number is not always enough to send from it: some countries also require an approved registration for the sender.

Parámetros

number_idstring

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

Carga de respuesta

name

nullable string

obligatorio

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

reference

nullable string

obligatorio

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

id

string

obligatorio

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

obligatorio

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

obligatorio

Phone number in E.164 format.

country_code

string

obligatorio

ISO 3166-1 alpha-2 country code.

number_type

string

obligatorio

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

obligatorio

Capabilities supported by this number.

status

string

obligatorio

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

obligatorio

When this number was allocated to your workspace.

releases_at

nullable string

obligatorio

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

obligatorio

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.

Mostrar atributos secundarios

pricing

nullable object

obligatorio

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.

Mostrar atributos secundarios

pricing.recurring_price

nullable object

obligatorio

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.

Mostrar atributos secundarios

pricing.recurring_period

nullable object

obligatorio

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

Mostrar atributos secundarios

pricing.intervals_per_charge

nullable integer

obligatorio

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

obligatorio

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.

Mostrar atributos secundarios

pricing.error.type

string

obligatorio

Broad category for coarse client branching.

Possible values: auth_error, bad_request_error, billing_error, client_closed_request_error, conflict_error, gone_error, internal_error, misdirected_error, not_found_error, not_implemented_error, payload_too_large_error, permission_error, precondition_error, rate_limit_error, service_unavailable_error, too_early_error, validation_error

pricing.error.code

string

obligatorio

Opaque, stable, unique error identifier. Never reused.

pricing.error.name

string

obligatorio

Human-readable slug for log readability. Paired with code, never replaces it.

pricing.error.message

string

obligatorio

Human-readable description. Not stable; clients must not parse it.

pricing.error.param

string

Identifies the offending field. Omitted when not applicable.

pricing.error.doc_url

string

obligatorio

Stable link to the docs page for this error code.

pricing.error.request_id

string

obligatorio

Request correlation ID for support and troubleshooting. Also returned in the X-Request-Id response header.

pricing.error.vendor_code

string

Verbatim error code from an external system, such as an SMTP response code or a payment decline code. Present only when the code may help you resolve the error.

pricing.error.details

array of object

Per-field validation errors. Present only on validation_error responses.

Mostrar atributos secundarios

pricing.error.remediation

string

A human-readable next step to resolve this error. Present when a recovery is known.

pricing.error.next

array of object

The steps that resolve this error. Perform them in order, re-reading after each; a wait or terminal step is always last. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts.

Mostrar atributos secundarios

pricing.error.next.kind

string

obligatorio

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

pricing.error.next.description

string

obligatorio

A short, human-readable label for the step, suitable for display.

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

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

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

pricing.error.quota

object

The quota limit that refused a resource change. A change in a workspace is checked against its organization's limit and any limit set for its workspace; the organization limit is reported when both refuse. When scope is workspace, follow the response remediation instead of the error code's organization-wide recovery guidance. An organization administrator can raise or remove the workspace ceiling; the shared organization limit still applies.

Mostrar atributos secundarios

Continúa con la documentación, guías y ejemplos de este tema.

Obtener un resumen de implementación

const allocated = await bird.numbers.get("nda_01krdgeqcxet5s7t44vh8rt9mg");
// A country that asks for ownership paperwork answers here; most answer null.
console.log(allocated.status, allocated.ownership ?? "no paperwork required");

allocated = client.numbers.get("nda_01krdgeqcxet5s7t44vh8rt9mg")
# A country that asks for ownership paperwork answers here; most answer None.
print(allocated.status, allocated.ownership or "no paperwork required")

allocated, err := client.Numbers.Get(context.Background(), "nda_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
// A country that asks for ownership paperwork answers on Ownership; most
// answer nil.
fmt.Println(allocated.Status)

$allocated = $bird->numbers->get('nda_01krdgeqcxet5s7t44vh8rt9mg');
// A country that asks for ownership paperwork answers here; most answer null.
echo $allocated->getStatus(), "\n";

bird numbers get <number-id>

curl -X GET "https://us1.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN"

Respuesta200

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

Get an allocated number

Parámetros

Carga de respuesta

Recursos relacionados