> ## 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. # Request physical Terminal hardware > Requests one physical Terminal for an existing Location. Ionic manages hardware selection, delivery, activation, and supported capabilities. Poll the returned request until it becomes `ready`, then retain its `terminal_id` for payments. A request in `requires_action` includes the next steps in `required_actions`. ## OpenAPI ````yaml /openapi/terminal-management.yaml post /terminal_provisioning_requests openapi: 3.0.3 info: title: Ionic Terminal Management API version: '2026-08-26' description: | Request physical Terminal hardware, inspect Merchant-owned Terminals, and read Ionic's terminal batch and settlement records. Every resource is scoped to the authenticated Merchant and the secret key's test or live mode. Request bodies never select `merchant_id` or `livemode`. Platforms can use `Ionic-Account` on delegated reads and provisioning requests; batch refresh is available only to a Merchant's own secret key. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for the selected environment. security: - secretKey: [] tags: - name: Terminal Provisioning description: Request physical hardware and track fulfillment. - name: Terminals description: Inspect Merchant-owned Terminal inventory and readiness. - name: Terminal Batches description: Read Ionic batch, item, and settlement records. paths: /terminal_provisioning_requests: post: tags: - Terminal Provisioning summary: Request physical Terminal hardware description: | Requests one physical Terminal for an existing Location. Ionic manages hardware selection, delivery, activation, and supported capabilities. Poll the returned request until it becomes `ready`, then retain its `terminal_id` for payments. A request in `requires_action` includes the next steps in `required_actions`. operationId: createTerminalProvisioningRequest parameters: - $ref: '#/components/parameters/IonicAccount' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTerminalProvisioningRequest' example: location_id: loc_R7pA3nB9qK2mX5 label: Front counter metadata: lane: '1' responses: '201': description: The durable provisioning request. content: application/json: schema: $ref: '#/components/schemas/TerminalProvisioningRequest' example: id: tprov_R7pA3nB9qK2mX5sJ4wF8tL6h object: terminal.provisioning_request merchant_id: mer_J4wF8tL6hC9vN2 livemode: false location_id: loc_R7pA3nB9qK2mX5 label: Front counter status: requested required_actions: [] terminal_id: null metadata: lane: '1' created_at: 1787625600 updated_at: 1787625600 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/WriteForbidden' '404': $ref: '#/components/responses/LocationNotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - terminals:write components: parameters: IonicAccount: name: Ionic-Account in: header required: false description: Merchant ID when an authorized Platform acts for a connected Merchant. schema: type: string pattern: ^mer_[0-9A-Za-z]{14}$ IdempotencyKey: name: Idempotency-Key in: header required: true description: Reuse only when retrying the same route and request body. schema: type: string minLength: 1 maxLength: 255 schemas: CreateTerminalProvisioningRequest: type: object additionalProperties: false required: - location_id - label properties: location_id: type: string pattern: ^loc_[0-9A-Za-z]{14}$ description: Location owned by the same Merchant and key mode. label: type: string minLength: 1 maxLength: 100 metadata: $ref: '#/components/schemas/Metadata' TerminalProvisioningRequest: type: object additionalProperties: false required: - id - object - merchant_id - livemode - location_id - label - status - required_actions - terminal_id - metadata - created_at - updated_at properties: id: type: string pattern: ^tprov_[0-9A-Za-z]{24}$ object: type: string enum: - terminal.provisioning_request merchant_id: type: string pattern: ^mer_[0-9A-Za-z]{14}$ livemode: type: boolean location_id: type: string pattern: ^loc_[0-9A-Za-z]{14}$ label: type: string status: type: string enum: - requested - processing - requires_action - ready - failed - canceled description: >- `ready` means `terminal_id` is assigned and the Terminal resource can be retrieved. required_actions: type: array items: type: string description: >- Additive action identifiers. Empty unless Merchant action is required. terminal_id: type: string pattern: ^tmr_[0-9A-Za-z]{14}$ nullable: true metadata: $ref: '#/components/schemas/Metadata' created_at: type: integer format: int64 description: Unix epoch seconds. updated_at: type: integer format: int64 description: Unix epoch seconds. Metadata: type: object description: >- Up to 50 string keys; keys are at most 40 characters and values are at most 500 characters. maxProperties: 50 additionalProperties: type: string maxLength: 500 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string responses: BadRequest: description: Invalid JSON, identifier, fields, filters, or cursor. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' WriteForbidden: description: >- Inactive Merchant, invalid delegation, or missing `terminals:write` permission. content: application/json: schema: $ref: '#/components/schemas/Error' LocationNotFound: description: The Location was not found for the Merchant and key mode. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Idempotency or resource-state conflict. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer bearerFormat: Ionic secret key description: >- Merchant secret key, or an authorized Platform secret key with delegation where documented. ````