<Intro>

<EndpointHeader />

<Description>

Orders a number for your workspace and starts its monthly charge. Pass a
number from `GET /v1/numbers/available`. Whether the number is already in
inventory or acquired from a supplier, the response contains an order.

Most orders complete immediately and return `201` with `status` of
`completed` and `number_id` populated. Read the number with
`GET /v1/numbers/{number_id}`. An order that cannot complete in the request
returns `202`; poll `GET /v1/numbers/orders/{order_id}` until it is
`completed` or `failed`.

A `412` means the workspace has not
completed the identity verification required to acquire a sender. Complete
it, then retry.

</Description>

</Intro>

<Payload kind="request">

<Field name="number" type="string" required>

<Description>

The number to acquire, in E.164 format, as returned by `GET /v1/numbers/available`.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

Identifier of this purchase order.

</Description>

</Field>

<Field name="number" type="string" required>

<Description>

The number being acquired, in E.164 format.

</Description>

</Field>

<Field name="country_code" type="string" required />

<Field name="number_type" type="string" required>

<Description>

Physical type of the number being acquired.

</Description>

</Field>

<Field name="status" type="string" required />

<Field name="number_id" type="nullable string">

<Description>

Identifier of the number this order produced, set when `status` is `completed`. Pass it as `number_id` to `GET /v1/numbers/{number_id}` or `DELETE /v1/numbers/{number_id}`. `null` until the order completes.

</Description>

</Field>

<Field name="failure_reason" type="nullable string">

<Description>

Human-readable reason the purchase failed. `null` unless status is failed. An order can fail some time after it was created, so `updated_at` tells you when the failure was recorded rather than when the order was placed.

</Description>

</Field>

<Field name="completed_at" type="nullable string">

<Description>

When the purchase completed and the number became owned (status completed). `null` for orders still in progress or failed.

</Description>

</Field>

<Field name="created_at" type="string" required />

<Field name="updated_at" type="string" required />

</Payload>