> ## 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. # Check a Terminal's connection > Performs one read-only connection check against the Terminal's active integration, stores the normalized observation, and returns the refreshed Terminal. This operation never initiates a payment. A failed check does not replace the last known connection state. Platforms can select an authorized connected Account with `Ionic-Account`. This operation intentionally has no idempotency key because every request asks for a new observation. ## OpenAPI ````yaml /openapi/terminal-management.yaml post /terminals/{id}/connection_observations openapi: 3.0.3 info: title: Ionic Terminal Management API version: '2026-09-02' 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 use `Ionic-Account` for the same inventory, provisioning, connection-observation, and batch operations on an authorized connected Account. Every test Account automatically has two Ionic test Locations and three ready simulated Terminals. Their IDs are unique to the Account, while the `test_profile` catalog is universal: `approved`, `declined`, and `delayed`. Physical hardware is created only through `POST /terminal_provisioning_requests`. 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: /terminals/{id}/connection_observations: post: tags: - Terminals summary: Check a Terminal's connection description: | Performs one read-only connection check against the Terminal's active integration, stores the normalized observation, and returns the refreshed Terminal. This operation never initiates a payment. A failed check does not replace the last known connection state. Platforms can select an authorized connected Account with `Ionic-Account`. This operation intentionally has no idempotency key because every request asks for a new observation. operationId: observeTerminalConnection parameters: - $ref: '#/components/parameters/TerminalId' - $ref: '#/components/parameters/IonicAccount' responses: '200': description: The Terminal with the newly persisted connection observation. content: application/json: schema: $ref: '#/components/schemas/Terminal' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/RefreshForbidden' '404': $ref: '#/components/responses/TerminalNotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/Unavailable' security: - secretKey: - terminals:read components: parameters: TerminalId: name: id in: path required: true description: Ionic Terminal ID. schema: type: string pattern: ^tmr_[0-9A-Za-z]{14}$ 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}$ schemas: Terminal: type: object additionalProperties: false required: - id - object - merchant_id - location_id - livemode - label - device - status - connection_status - connection_status_stale - connection_observed_at - capabilities - last_seen_at - metadata - created_at - updated_at properties: id: type: string pattern: ^tmr_[0-9A-Za-z]{14}$ object: type: string enum: - terminal merchant_id: type: string pattern: ^mer_[0-9A-Za-z]{14}$ location_id: type: string pattern: ^loc_[0-9A-Za-z]{14}$ livemode: type: boolean test_profile: type: string enum: - approved - declined - delayed description: | Built-in deterministic outcome for this Account-owned test Terminal. Omitted for physical and non-fixture Terminals. An exact test-helper override for a PaymentIntent takes precedence. label: type: string device: $ref: '#/components/schemas/TerminalDevice' status: type: string enum: - provisioning - requires_action - ready - disabled - replacing - failed connection_status: type: string enum: - online - offline - unknown description: >- Freshness-aware connection status; stale observations are returned as `unknown`. connection_status_stale: type: boolean connection_observed_at: type: integer format: int64 nullable: true description: Unix epoch seconds of the last connection observation. capabilities: type: object additionalProperties: $ref: '#/components/schemas/TerminalCapability' description: >- Capability names are additive; inspect each entry's status before use. last_seen_at: type: integer format: int64 nullable: true metadata: $ref: '#/components/schemas/Metadata' created_at: type: integer format: int64 updated_at: type: integer format: int64 TerminalDevice: type: object additionalProperties: false required: - model - serial_number_last4 properties: model: type: string serial_number_last4: type: string pattern: ^[0-9A-Za-z]{4}$ TerminalCapability: type: object additionalProperties: false required: - support - status properties: support: type: string enum: - supported - unsupported - conditional status: type: string enum: - ready - pending - not_ready - unknown reason: type: string description: Additive Ionic reason code when the capability is not ready. 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' RefreshForbidden: description: >- Platform delegation is not accepted, the Merchant is inactive, or `terminals:read` is missing. content: application/json: schema: $ref: '#/components/schemas/Error' TerminalNotFound: description: The Terminal was not found for the Merchant and key mode. 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' Unavailable: description: Fresh Terminal provider information is temporarily unavailable. 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. ````