Units - Endstate API

What is a unit?

A unit is the digital identity of a single physical item — its digital twin and its certificate of authenticity. Even if two items are identical SKUs (same product, same size, same color), each one is its own unit with its own identity, its own chip, and its own issuance history. Units live inside a collection. A collection defines the group (a product line, a drop, a release); a unit is one item within it.

Why units matter

Register items. Create a unit for each physical item when it enters your workflow — before it ships, before it’s paired to a chip.
Map to your inventory. Use external_id to tie each unit back to your own SKU, order line, or serial number. Filter lists by external_id to look up units without storing Endstate IDs.
Track issuance. A unit’s collection.token.status tells you whether the item has been issued — pending means the unit exists but has no chip yet; active means a chip is paired and the unit has a collection.token.serial within its collection.
Verify on tap. When a user taps an NFC chip, the API returns the unit record attached to it. That record is what you display, validate, or act on.

Unit object

string (UUID)

The unit’s unique identifier. Stable; use this as your durable reference in Endstate.

external_id

string | null

Your own identifier for this item — SKU, order line ID, serial number, or any opaque string. Must be unique within your organization if provided. Null if not set.

name

string | null

A human-readable label for the item (e.g. "Black Hoodie — Size M"). Optional; null if not set.

attributes

object | null

Free-form JSON you attach to this unit. Use this for any item-level metadata that does not have a dedicated field — color, size, batch number, custom fields. No enforced schema; store whatever your integration needs.

redirect_url

string | null

Where a user is sent after tapping this unit’s chip. Overrides the collection and organization-default redirects. Null if not set — resolution then falls through to the collection redirect, then your organization default. See Tap redirects.

created_at

string (ISO-8601)

When the unit was created.

collection

object

The collection this unit belongs to.

Show collection fields

collection.id

string (UUID)

The collection’s unique identifier.

collection.name

string | null

The collection’s name.

collection.external_id

string | null

Your identifier for the collection, if set.

collection.contract

object

Registry details for the collection — address (string), chain_id (integer), and status (deploying, active, or failed). See Collections for what each field means.

collection.token

object

The unit’s issuance status within this collection.

Show token fields

collection.token.status

string

The unit’s issuance status. pending — the unit has no chip paired yet. active — a chip is paired and the unit has been issued a serial number within the collection.

collection.token.serial

integer | null

The unit’s serial number within its collection. Assigned when collection.token.status becomes active. Null while still pending. Serial numbers are assigned in the order items are issued.

chips

array

The NFC chips paired to this unit. Most units have exactly one chip; the array is empty until a chip is paired.

Show chip fields

chips[].chip_id

string

The chip’s identifier (10 hex characters). This is the value that appears in the tap URL.

chips[].is_test

boolean

true for test chips used in integration testing without hardware. false for chips on real physical items.

chips[].scan_count

integer

The number of times this chip has been successfully verified.

chips[].created_at

string (ISO-8601)

When the chip was paired to this unit.

Create a unit

POST /v1/units

collection_id

string (UUID)

required

The ID of the collection this unit belongs to. The collection must already be provisioned (contract.status: "active"). Required.

external_id

string

Your own identifier for this item. Must be unique within your organization. Optional.

name

string

A human-readable label for the item. Optional.

attributes

object

Free-form JSON metadata to attach to the unit. Optional.

redirect_url

string

Where a user is sent after tapping this unit’s chip. Must be a valid absolute URL. Optional — you can also set or change it later with PATCH /v1/units/ {unit_id}. See Tap redirects.

Example

curl https://api2.endstate.io/v1/units \
  -X POST \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "sku-hoodie-black-m-001",
    "name": "Black Hoodie — Size M",
    "attributes": { "color": "black", "size": "M" }
  }'

{
  "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "external_id": "sku-hoodie-black-m-001",
  "name": "Black Hoodie — Size M",
  "attributes": { "color": "black", "size": "M" },
  "redirect_url": null,
  "created_at": "2026-05-14T10:30:00.000Z",
  "collection": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Summer Drop 2026",
    "external_id": null,
    "contract": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain_id": 84532,
      "status": "active"
    },
    "token": {
      "status": "pending",
      "serial": null
    }
  },
  "chips": []
}

The unit is returned at the top level, like every single-resource response — see Response shape. It is created with collection.token.status: "pending"; no serial is assigned yet — that happens when a chip is paired. See Lifecycle below.

Lifecycle

Units move through a simple two-state lifecycle:

Create the unit

POST /v1/units — the unit is created with collection.token.status: "pending" and an empty chips array. No serial number yet.

Pair a chip

POST /v1/chips with unit_id and the chip’s identifiers. Pairing links the physical item to its digital record and triggers issuance.

Unit is issued

Issuance is asynchronous. Poll GET /v1/units/{unit_id} until collection.token.status is "active". When active, collection.token.serial holds the unit’s serial number within the collection.

Poll GET /v1/units/{unit_id} to check issuance status.

Endpoints

Method	Path	Description
`POST`	`/v1/units`	Create a unit
`GET`	`/v1/units`	List units (cursor-paginated; filter by `external_id`)
`GET`	`/v1/units/{unit_id}`	Fetch a single unit by ID
`PATCH`	`/v1/units/{unit_id}`	Update a unit’s `redirect_url`
`POST`	`/v1/units/{unit_id}/chip-replacements`	Replace the unit’s chip (until the unit is claimed)
`GET`	`/v1/units/{unit_id}/chip-replacements/{replacement_id}`	Poll a chip replacement’s status
`POST`	`/v1/units/{unit_id}/claims`	Claim the unit — session token required
`POST`	`/v1/units/{unit_id}/transfers`	Transfer the unit — session token required

These endpoints take an API key, except claim and transfer creation, which require a session token (status polling takes either). See Authentication for header format and credential types. For full request/response schemas, see the API reference.

Next steps

Chips

Pair an NFC chip to a unit to complete its digital record and trigger issuance.

Collections

Understand how collections group units and define the serial-number namespace.

Tap redirects

Send a user to your own destination after they tap this unit’s chip.

​What is a unit?

​Why units matter

​Unit object

​Create a unit

​Example

​Lifecycle

​Endpoints

​Next steps

Chips

Collections

Tap redirects

What is a unit?

Why units matter

Unit object

Create a unit

Example

Lifecycle

Endpoints

Next steps