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

List devices#

GET/v1/devices

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

Create device#

POST/v1/devicesIdempotent

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
Bash
curl -X POST https://api.withflintpay.com/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Front Counter iPad",
    "location_id": "loc_123",
    "hardware_fingerprint": "ios-device-uuid-123",
    "metadata": {
      "register": "front_counter"
    }
  }'
JSON
{
  "data": {
    "device_id": "dev_123",
    "name": "Front Counter iPad",
    "status": "active",
    "merchant_id": "mer_123",
    "location_id": "loc_123",
    "hardware_fingerprint": "ios-device-uuid-123",
    "metadata": {
      "register": "front_counter"
    },
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "already_existed": true
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get device#

GET/v1/devices/{device_id}

Returns a single device by ID.

Path parameters
device_idstringrequired

Flint device ID.

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

Update device#

PATCH/v1/devices/{device_id}Idempotent

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
namestring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/devices/dev_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Front Counter iPad 2",
    "metadata": {
      "floor": "1",
      "register": "front_counter"
    }
  }'
JSON
{
  "data": {
    "device_id": "dev_123",
    "name": "Front Counter iPad",
    "status": "active",
    "merchant_id": "mer_123",
    "location_id": "loc_123",
    "hardware_fingerprint": "ios-device-uuid-123",
    "metadata": {
      "register": "front_counter"
    },
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete device#

DELETE/v1/devices/{device_id}Idempotent

Soft-deletes a device by transitioning its status to deleted.

Path parameters
device_idstringrequired

Flint device ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X DELETE https://api.withflintpay.com/v1/devices/dev_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "device_id": "dev_123",
    "name": "Front Counter iPad",
    "status": "active",
    "merchant_id": "mer_123",
    "location_id": "loc_123",
    "hardware_fingerprint": "ios-device-uuid-123",
    "metadata": {
      "register": "front_counter"
    },
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc