Get an allocated number

GET

/v1/numbers/{number_id}

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

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

held, 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(held.Status)

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

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

Response200

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

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. Holding a number is not always enough to send from it: some countries also require an approved registration for the sender.

Paramètres

number_id

string

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

Contenu de la réponse

string

obligatoire

Identifier of this allocated number. Pass it as number_id to read this number, or to release it when kind is dedicated.

kind

string

obligatoire

How this number is allocated to the workspace. dedicated is owned solely by this workspace and billed as a subscription. shared is a shortcode shared across workspaces and managed by us.

Possible values: dedicated, shared

number

string

obligatoire

Phone number in E.164 format.

country_code

string

obligatoire

number_type

string

obligatoire

Physical type of this phone number.

capabilities

array of string

obligatoire

Channel capabilities supported by this number.

status

string

obligatoire

Whether this number can carry traffic.

active means this number is allocated to your workspace and usable.
pending_compliance means this number is allocated to your workspace and billed, but it cannot carry traffic until the ownership paperwork its country requires is accepted. Read ownership.next for what advances it, and re-read later if ownership is momentarily null.
released means this number is no longer allocated to your workspace.

Holding a number is not always enough to send from it: some destination countries also require an approved registration for the sender.

Possible values: active, pending_compliance, released

allocated_at

string

obligatoire

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

Where this number stands with the ownership paperwork its country requires. null when the country requires none, which is the usual case: a number with no ownership object is usable as soon as it is allocated. Also null when that standing cannot be established right now; status still reads pending_compliance while the number is blocked, so re-read this field rather than caching its absence. We manage the paperwork for shared short codes, so this field is always null for them.

Afficher les attributs enfants

ownership.satisfied

boolean

obligatoire

Whether the paperwork is accepted. Read next for what advances it while this is false. Whether sending is currently refused is reported by blocked_at instead: a number bought before its country asked for anything is unsatisfied and still usable until a review says otherwise.

ownership.blocked_at

nullable string

When the number stopped being able to carry traffic, and null while it can. Always null when satisfied is true, but null does not imply it: a number whose country began asking after you bought it is usable with its paperwork still outstanding. A number can also arrive blocked, and one that was usable can be blocked again if its approval is withdrawn.

ownership.next

array of object

obligatoire

What you do about it, in the order to do it. Empty only when satisfied is true, so while anything is outstanding there is always at least one step. When what you already sent is being reviewed and nothing is needed from you, that step has kind wait and says so. Re-read it after each call rather than caching the first list you saw.

Afficher les attributs enfants

ownership.next.kind

string

obligatoire

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

obligatoire

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.

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

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

held, 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(held.Status)

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

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

Response200

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