---
title: "Pair a device by its code"
method: POST
path: "/v1/screens/claim"
tags: ["screens"]
---

# Pair a device by its code

`POST /v1/screens/claim`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/screens/claim`
- Auth: HTTP bearer

Pair a device using its 6-digit pairing code, creating a new screen. Provide `code`, `name`, and an optional `nodeId`. This endpoint is rate-limited because the pairing code space is small, and is refused if your account is suspended or cancelled.

Claims the device showing a 6-digit pairing code into this workspace as a new screen.

## Request body

- object
  - `code` string, required: The 6-digit code the device shows.
  - `name` string: Screen name. Default "New screen".
  - `nodeId` string: Location to file the screen under.
  - `billingGroupId` string

## Response `201`

Success.

- object
  - `data` object, required
    - `screenId` string, required
    - `name` string, required
    - `previousScreen` object, nullable, required: The screen this same device was last paired to in this workspace, if any.
      - `screenId` string, required
      - `name` string, required
      - `deletedAt` string, nullable, required: ISO-8601 timestamp (UTC).
      - `claimedAt` string, nullable, required: ISO-8601 timestamp (UTC).

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `404`: `invalid_code`: no device is waiting with that code.
- `409`: `ambiguous_code` or `already_claimed`.
- `410`: `code_expired`.
- `422`: `code` missing, or a foreign location.
- `429`: Too many failed codes; honour `Retry-After`.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)