> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The provisioning request object

> Request physical Terminal hardware for a Location and track the request until the Terminal is ready.

<ResponseExample>
  ```json The provisioning request object theme={null}
  {
    "id": "tprov_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "terminal.provisioning_request",
    "location_id": "loc_01JEXAMPLE2K8V4N9C6M1Q7R",
    "label": "Front counter",
    "status": "requested",
    "required_actions": [],
    "terminal_id": null,
    "metadata": {},
    "livemode": false
  }
  ```
</ResponseExample>

A provisioning request (`tprov_…`) is the workflow that delivers a physical
[Terminal](/api-reference/terminals) to a [Location](/api-reference/terminal-locations). Your server creates it with a Location and a
label. Ionic manages hardware selection, delivery, activation, and supported
capabilities. Physical hardware is created only through this request.

Poll the request until it becomes `ready`, then keep its `terminal_id` and use
it to [process payments](/api-reference/terminal-payments). Test accounts already have simulated Terminals, so they do not need
a request. See [The Terminal object](/concepts/terminal-object) and
[Accept in-person terminal payments](/guides/in-person-payments). Platforms follow
[In-person payments for connected accounts](/guides/connect-in-person-payments).

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the provisioning request (`tprov_…`).
</ResponseField>

<ResponseField name="location_id" type="string">
  ID of the location where the terminal will be used (`loc_…`).
</ResponseField>

<ResponseField name="label" type="string">
  Name for the terminal, shown in your records.
</ResponseField>

<ResponseField name="status" type="string">
  `ready` means `terminal_id` is assigned and the Terminal resource can be retrieved.
</ResponseField>

<ResponseField name="required_actions" type="array of strings">
  Additive action identifiers. Empty unless Merchant action is required.
</ResponseField>

<ResponseField name="terminal_id" type="string | null">
  ID of the terminal created by this request (`tmr_…`). Null until the request is `ready`.
</ResponseField>

<ResponseField name="metadata" type="object">
  Up to 50 string keys; keys are at most 40 characters and values are at most 500 characters.
</ResponseField>

See every field in the response of [Retrieve a Terminal provisioning request](/api-reference/terminal-provisioning/retrieve-a-terminal-provisioning-request).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [List Terminal provisioning options](/api-reference/terminal-provisioning/list-terminal-provisioning-options) | See the integrations and device models available for new requests. |
| [Request physical Terminal hardware](/api-reference/terminal-provisioning/request-physical-terminal-hardware) | Request one physical Terminal for an existing Location. |
| [List Terminal provisioning requests](/api-reference/terminal-provisioning/list-terminal-provisioning-requests) | Review requests for the Merchant and mode. |
| [Retrieve a Terminal provisioning request](/api-reference/terminal-provisioning/retrieve-a-terminal-provisioning-request) | Check a request's latest status and `terminal_id`. |

## Statuses

| Status | Meaning |
| - | - |
| `requested` | The request was created. Retrieve the request until it changes. |
| `processing` | Ionic is working on the request. Retrieve the request until it changes. |
| `requires_action` | The merchant needs to act. `required_actions` lists the next steps. Complete the listed actions. |
| `ready` | `terminal_id` is assigned and the Terminal can be retrieved. Use `terminal_id` for payments. |
| `failed` | The request failed. |
| `canceled` | The request was canceled. |

## Rules

* The provisioning catalog is the same for every account and mode. It requires an account secret key; Platform keys and `Ionic-Account` are not accepted.
* The `location_id` must belong to the same Merchant and mode as the key.
* `required_actions` is empty unless the Merchant must act, and action identifiers are additive.
* Do not use a Terminal's status to infer the state of an unfinished request. The request exposes a `terminal_id` only when it is `ready`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.