---
title: "ListDevices"
method: GET
path: "/v2/devices"
tags: ["Devices"]
---

# ListDevices

`GET /v2/devices`

List devices associated with the merchant. Currently, only Terminal API
devices are supported.

## Query parameters

- `cursor` string
- `sort_order` 'DESC' | 'ASC' — The order (e.g., chronological or alphabetical) in which results from a request are returned.
- `limit` integer
- `location_id` string

## Response `200`

Success

- ListDevicesResponse
  - `errors` Error[] — Information about errors that occurred during the request.
    - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API.
    - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.
  - `devices` Device[] — The requested list of `Device` objects.
    - `id` string — A synthetic identifier for the device. The identifier includes a standardized prefix and is otherwise an opaque id generated from key device fields.
    - `attributes` DeviceAttributes, required
      - `type` 'TERMINAL' | 'HANDHELD', required — An enum identifier of the device type.
      - `manufacturer` string, required — The maker of the device.
      - `model` string, nullable — The specific model of the device.
      - `name` string, nullable — A seller-specified name for the device.
      - `manufacturers_id` string, nullable — The manufacturer-supplied identifier for the device (where available). In many cases, this identifier will be a serial number.
      - `updated_at` string — The RFC 3339-formatted value of the most recent update to the device information. (Could represent any field update on the device.)
      - `version` string — The current version of software installed on the device.
      - `merchant_token` string, nullable — The merchant_token identifying the merchant controlling the device.
    - `components` Component[], nullable — A list of components applicable to the device.
      - `type` 'APPLICATION' | 'CARD_READER' | 'BATTERY' | 'WIFI' | 'ETHERNET' | 'PRINTER', required — An enum for ComponentType.
      - `application_details` DeviceComponentDetailsApplicationDetails
        - `application_type` 'TERMINAL_API'
        - `version` string — The version of the application.
        - `session_location` string, nullable — The location_id of the session for the application.
        - `device_code_id` string, nullable — The id of the device code that was used to log in to the device.
      - `card_reader_details` DeviceComponentDetailsCardReaderDetails
        - `version` string — The version of the card reader.
      - `battery_details` DeviceComponentDetailsBatteryDetails
        - `visible_percent` integer, nullable — The battery charge percentage as displayed on the device.
        - `external_power` 'AVAILABLE_CHARGING' | 'AVAILABLE_NOT_IN_USE' | 'UNAVAILABLE' | 'AVAILABLE_INSUFFICIENT' — An enum for ExternalPower.
      - `wifi_details` DeviceComponentDetailsWiFiDetails
        - `active` boolean, nullable — A boolean to represent whether the WiFI interface is currently active.
        - `ssid` string, nullable — The name of the connected WIFI network.
        - `ip_address_v4` string, nullable — The string representation of the device’s IPv4 address.
        - `secure_connection` string, nullable — The security protocol for a secure connection (e.g. WPA2). None provided if the connection is unsecured.
        - `signal_strength` DeviceComponentDetailsMeasurement — A value qualified by unit of measure.
          - `value` integer, nullable — Value of measure.
        - `mac_address` string, nullable — The mac address of the device in this network.
      - `ethernet_details` DeviceComponentDetailsEthernetDetails
        - `active` boolean, nullable — A boolean to represent whether the Ethernet interface is currently active.
        - `ip_address_v4` string, nullable — The string representation of the device’s IPv4 address.
        - `mac_address` string, nullable — The mac address of the device in this network.
    - `status` DeviceStatus
      - `category` 'AVAILABLE' | 'NEEDS_ATTENTION' | 'OFFLINE'
  - `cursor` string — The pagination cursor to be used in a subsequent request. If empty, this is the final response. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information.

---

[API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/versions/6a5164284e41/schema)