---
title: "Claim an unclaimed device"
method: POST
path: "/api/devices"
tags: ["Devices"]
---

# Claim an unclaimed device

`POST /api/devices`

## Request

- Base URL: `https://trmnl.com`
- URL: `https://trmnl.com/api/devices`
- Auth: HTTP bearer

Links a device that has not been claimed yet (a new device, or a QR code scan) to this account. Sets up the starter playlist item the first time. friendly_id is printed on the device screen during setup.

## Request body

- object
  - `friendly_id` string, required: The code shown on the device during setup

## Response `200`

Claimed

- object
  - `data` Device
    - `management` object
    - `id` integer
    - `name` string
    - `friendly_id` string
    - `mac_address` string: All but the last two bytes are masked for an API key or an agent; the account API key reads it whole.
    - `firmware_version` string, nullable: Version the device reported at its last check-in
    - `firmware_channel` string: Release channel the device follows
    - `ota_enabled` boolean: Whether the device accepts over-the-air updates
    - `pinned_firmware_version` string, nullable: Version the device is pinned to, if any
    - `battery_voltage` number, nullable
    - `rssi` integer, nullable
    - `wifi_band` string, nullable: WiFi band the device is connected on ("2.4" or "5")
    - `refresh_interval` integer: Seconds between check-ins, 300 to 86400
    - `orientation` integer
    - `sleep_screen_enabled` boolean
    - `low_battery_notification_enabled` boolean
    - `auto_advance` boolean: Beta: may change or go away. Present only when management.writable_fields lists it
    - `sleep_mode_enabled` boolean
    - `sleep_start_time` integer
    - `sleep_end_time` integer
    - `sleep_until` string, date_time, nullable: A one-time sleep the device takes at its next check-in, then clears
    - `last_ping_at` string, date_time, nullable
    - `hardware_last_ping_at` string, date_time, nullable
    - `percent_charged` number
    - `wifi_strength` number
    - `mashup_layouts` object: The mashup layouts the device can show and the positions to fill in each; 3x3 lists none because its grid_config names them

## Other responses

- `400`: friendly_id is missing
- `401`: Unauthorized
- `422`: A concurrent claim already took the device
- `429`: Too many failed claims from this account or address

---

[API](https://skmtc.dev/trmnl/apis/trmnl-api.md) · [All operations](https://skmtc.dev/trmnl/apis/trmnl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trmnl/apis/trmnl-api/revisions/66179e6d663b?raw)