Terminal Device Monitoring

Use the Devices API to remotely monitor Square Terminals that are connected to the seller's storefront network. The Devices API provides methods to list and retrieve information about devices.

• Only Square Terminal devices running the Terminal API are represented in the Devices API.
• Calls to a Devices API endpoint use OAuth to identify callers and associated merchants and require DEVICES_READ permission to access the device information.
• The Devices API periodically provides updated device data, but not in real-time. If needed, use the PING Terminal action to get real-time information about a specific device.

The Device API's ListDevices and GetDevice endpoints return read-only data about the seller's devices, such as network connectivity, battery level, and software version. This data is represented as a Device object for a given device. A Device object has a unique ID associated with the device; for example, device:b27e76da-2779-4a92-b076-affcbe3ae94d.

Use the device.created webhook to subscribe to events for when devices are created for a seller's account.

The ListDevices endpoint doesn't require parameters, but supports filtering by location_id as well as parameters for paging through results (pagination).

The following request calls for a list of devices:

Use the GetDevice endpoint to get detailed information for a specific device.

The following request example uses the device_id in the request path parameter with device:b27e76da-2779-4a92-b076-affcbe3ae94d as the device_id value being passed. Note that the device_id value includes the device: prefix, and that the %3A characters represent the colon : in the request path parameter:

A Device object contains:

• The device ID.
• The device’s overall status, which is AVAILABLE, NEEDS_ATTENTION, or OFFLINE.
• A collection of device attributes representing the device as a whole. For example, these attributes can be the device type, model, and manufacturer.
• An array of components, which are additional details associated with the device. For example, these components are comprised of the device type, the device's running application, batteries, card readers, and network interfaces.

The following response example is a single device object and its id, status, attributes, and components information. If you use ListDevices, the response returns a list of devices for the given seller along with each device's information.

Note that components represents a wrapper object for all of the component entries for the given component type.

{
   "device": [
      {
        "id": "device:b27e76da-2779-4a92-b076-affcbe3ae94d",
        "status": {
          "category": "AVAILABLE"
        },
        "attributes": {
          "type": "TERMINAL",
          "manufacturer": "SQUARE",
          "model": "T2",
          "manufacturers_id": "232CS149B1002318",
          "version": "5.27.0050",
          "merchant_token": "6B3KQJN1024K7",
          "updated_at": "2022-09-29T19:50:42.862Z"
        },
        "components": [
          {
            "type": "APPLICATION",
            "application_details": {
              "application_type": "TERMINAL_API",
              "version": "6.0",
              "session_location": "1AENGX6B01J2J",
              "device_code_id": "77HKKEM3BD06Q"
            }
          },
          {
            "type": "CARD_READER",
            "card_reader_details": { 
              "version": "3.43.69"
            }
          },
          {
            "type": "BATTERY",
            "battery_details": {
              "visible_percent": 87,
              "external_power": "AVAILABLE_CHARGING"
            }
          },
          {
            "type": "WIFI",
            "wifi_details": {
              "active": true,
              "ssid": "Staff HotSpot",
              "ip_v4_address": "10.1.10.237",
              "secure_connection": "WPA/WPA2 PSK",
              "signal_strength": {
                "value": 3
              }
            }
          },
          {
            "type": "ETHERNET",
            "ethernet_details": {
              "active": false
            }
          },
        ]
      }
    }
  ]
}