FlintflintDocs

Devices

Devices represent merchant hardware or app installations that belong to your account: a register, kiosk, or terminal app instance. A device can be assigned to a location, and that assignment feeds effective settings resolution: querying effective settings with a device_id applies device-level overrides and the device's inherited location automatically.

Pass a hardware_fingerprint at creation to make device registration safe to repeat: when a matching device already exists, Flint returns the existing record instead of creating a duplicate. Clearing a device's location_id detaches it from the location without deleting it.

See the settings reference for how device scope participates in settings inheritance and policies.

Endpoints

The Device object#

Every field on a device, as returned by retrieve and carried by the endpoints below.

Attributes
created_atstring

RFC3339 timestamp.

device_idstringrequired
hardware_fingerprintstring
location_idstring
merchant_idstring
metadatamap of string
namestringrequired
statusenumrequired
activedeleted
updated_atstring

RFC3339 timestamp.

JSON
{
  "created_at": "2026-03-17T14:30:00Z",
  "device_id": "dev_123",
  "hardware_fingerprint": "ios-device-uuid-123",
  "location_id": "loc_123",
  "merchant_id": "mer_123",
  "metadata": {
    "register": "front_counter"
  },
  "name": "Front Counter iPad",
  "status": "active",
  "updated_at": "2026-03-17T14:30:00Z"
}

List devices#

GET/v1/devicesRequires scope: accounts.devices.read or accounts.devices.write

Returns a paginated list of devices for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by device status.

activedeleted
location_idstring

Filter by assigned Flint location ID.

sort_byenum

Sort field.

namecreated_atupdated_at
sort_directionenum

Sort direction.

ascdesc
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/devices \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "created_at": "2026-03-17T14:30:00Z",
      "device_id": "dev_123",
      "hardware_fingerprint": "ios-device-uuid-123",
      "location_id": "loc_123",
      "merchant_id": "mer_123",
      "metadata": {
        "register": "front_counter"
      },
      "name": "Front Counter iPad",
      "status": "active",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create device#

POST/v1/devicesIdempotentRequires scope: accounts.devices.write

Creates a device for the authenticated merchant. If hardware_fingerprint matches an existing device, the existing device is returned with 200 OK and data.already_existed=true.

Request body
hardware_fingerprintstring
location_idstring
metadatamap of string
namestringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl -X POST https://api.withflintpay.com/v1/devices \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "hardware_fingerprint": "ios-device-uuid-123",
    "location_id": "loc_123",
    "metadata": {
      "register": "front_counter"
    },
    "name": "Front Counter iPad"
  }'

Get device#

GET/v1/devices/{device_id}Requires scope: accounts.devices.read or accounts.devices.write

Returns a single device by ID.

Path parameters
device_idstringrequired

Flint device ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/devices/dev_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "created_at": "2026-03-17T14:30:00Z",
    "device_id": "dev_123",
    "hardware_fingerprint": "ios-device-uuid-123",
    "location_id": "loc_123",
    "merchant_id": "mer_123",
    "metadata": {
      "register": "front_counter"
    },
    "name": "Front Counter iPad",
    "status": "active",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update device#

PATCH/v1/devices/{device_id}IdempotentRequires scope: accounts.devices.write

Applies a sparse update to a device. Send location_id=null to unassign a location.

Path parameters
device_idstringrequired

Flint device ID.

Request body
location_idstring
metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/devices/dev_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "floor": "1",
      "register": "front_counter"
    },
    "name": "Front Counter iPad 2"
  }'

Delete device#

DELETE/v1/devices/{device_id}IdempotentRequires scope: accounts.devices.write

Marks a device as deleted and returns its final state.

Path parameters
device_idstringrequired

Flint device ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/devices/dev_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc