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.

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

active
deleted

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/devices

Requires 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.

active
deleted

location_idstring

Filter by assigned Flint location ID.

sort_byenum

Sort field.

name
created_at
updated_at

sort_directionenum

Sort direction.

asc
desc

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

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": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create device#

POST/v1/devicesIdempotent

Requires 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

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

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}Idempotent

Requires 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

Same response as Get device.

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}Idempotent

Requires scope accounts.devices.write

Marks a device as deleted and returns its final state.

Path parameters

device_idstringRequired

Flint device ID.

Response · 200

Same response as Get device.

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

Was this helpful?