Collections - Endstate API

What is a collection?

A collection is a named group of related units — a product line, a drop, or a release. Every unit belongs to exactly one collection, and the collection defines the serial-number namespace shared across all units within it. Create a collection once per product group. Then create units inside it for each individual physical item.

Why it matters

Collections let you organize your products and enforce namespace boundaries:

Units within a collection receive sequential serial numbers that are unique within that collection.
Keeping separate product lines in separate collections avoids serial collisions and makes filtering your unit list predictable.
A unit cannot exist without a collection. You must create and provision a collection before you can add units to it.

Lifecycle

Create the collection

Call POST /v1/collections. The API returns 201 immediately. The collection’s contract.status is "deploying", meaning it is being provisioned. The registry is not yet ready for units.

Wait for provisioning

Provisioning is asynchronous. Poll GET /v1/collections/{collection_id} until contract.status is "active".

Add units

Once the collection is active, create units inside it with POST /v1/units, passing the collection’s id as collection_id.

Provisioning status values

`contract.status`	Meaning
`deploying`	The collection is being provisioned. Do not add units yet.
`active`	The collection is ready. You can create units.
`failed`	Provisioning failed. Contact Endstate support.

If you attempt to create a unit in a collection that has not yet reached active, the API returns collection.not_active (409).

Collection object

string

Unique identifier for the collection (UUIDv4).

name

string | null

Human-readable name you provided at creation.

external_id

string | null

Your own identifier for this collection, if you provided one. Unique within your organization. Useful for correlating with your internal systems. Null if not set.

redirect_url

string | null

Where a user is sent after tapping the chip on any unit in this collection, unless that unit sets its own redirect_url. Null if not set — resolution then falls through to your organization default. See Tap redirects.

contract

object

Registry details for the collection.

Show contract fields

contract.address

string

The collection’s unique registry address. Assigned at creation and returned immediately, including while contract.status is still deploying.

contract.chain_id

integer

The network identifier for this collection’s registry. Fixed at creation — your organization’s default network, or the chain_id you supplied to override it.

contract.status

string

The collection’s provisioning status. One of deploying, active, or failed. Poll this field after creation.

Create a collection

Request fields

name

string

required

A human-readable name for the collection (1–256 characters). For example, "Spring 2026 Hoodie".

symbol

string

A short identifier for the collection (1–4 characters). Derived from name if omitted. For example, "S26H".

external_id

string

Your own identifier for this collection. Must be unique within your organization. Omit if you do not need to correlate with an external system.

chain_id

integer

The network to create the collection on. Optional — when omitted, the collection is created on your organization’s default network, configured by Endstate at onboarding. An explicit value must be one of the networks enabled for your organization (allowed_chain_ids from GET /v1/settings); any other value returns validation.failed.

redirect_url

string

Where a user is sent after tapping a chip on any unit in this collection. Must be a valid absolute URL. Optional — you can also set or change it later with PATCH /v1/collections/{collection_id}. See Tap redirects.

Example

curl -X POST https://api2.endstate.io/v1/collections \
  -H "Authorization: Bearer end_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring 2026 Hoodie",
    "symbol": "S26H",
    "external_id": "hoodie-spring-2026"
  }'

{
  "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "name": "Spring 2026 Hoodie",
  "external_id": "hoodie-spring-2026",
  "redirect_url": null,
  "contract": {
    "address": "0x1111111111111111111111111111111111111111",
    "chain_id": 84532,
    "status": "deploying"
  }
}

The collection is returned at the top level, like every single-resource response (see Response shape). contract.address is assigned at creation and present immediately; symbol is accepted on create but not returned. Poll GET /v1/collections/{collection_id} until contract.status is "active".

Active collection (polled response)

{
  "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "name": "Spring 2026 Hoodie",
  "external_id": "hoodie-spring-2026",
  "redirect_url": null,
  "contract": {
    "address": "0x1111111111111111111111111111111111111111",
    "chain_id": 84532,
    "status": "active"
  }
}

Endpoints

Method	Path	Description
`POST`	`/v1/collections`	Create a collection
`GET`	`/v1/collections`	List collections (cursor-paginated; filter by `external_id`)
`GET`	`/v1/collections/{collection_id}`	Fetch a single collection by UUID
`PATCH`	`/v1/collections/{collection_id}`	Update a collection’s `redirect_url`

See the API reference for full request and response schemas.

Next steps

Units

Create units inside a collection to represent individual physical items.

Quickstart

Walk through the full flow: collection, unit, chip, and first verification.

Tap redirects

Send a user to your own destination after they tap a chip in this collection.

​What is a collection?

​Why it matters

​Lifecycle

​Provisioning status values

​Collection object

​Create a collection

​Request fields

​Example

​Active collection (polled response)

​Endpoints

​Next steps

Units

Quickstart

Tap redirects

What is a collection?

Why it matters

Lifecycle

Provisioning status values

Collection object

Create a collection

Request fields

Example

Active collection (polled response)

Endpoints

Next steps