Monitor Square Terminals

Applies to: Terminal API | Devices API

Learn how to remotely monitor Square Terminals that are connected to the seller's storefront network.

• Only Square Terminals 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 ListDevices and GetDevice endpoints of the Devices API 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 information about 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
            }
          },
        ]
      }
    }
  ]
}