CirculeID

Documentation

Start here

Everything you need to issue a passport, append supply chain events and verify a credential — with the standards each of those maps onto, so nothing you build is captive to this platform.

API referenceGet an API key
Protocol
JSON over HTTPS
Events
EPCIS 2.0 JSON-LD
Credentials
W3C VC 2.0

Definition

How do you issue a Digital Product Passport through an API?

Create a passport resource against a GS1 identifier with the product record, append EPCIS 2.0 events as the product moves, and issue W3C Verifiable Credentials for claims that must be provable. Reading resolves the identifier and returns the view the caller's credentials entitle them to.

The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Quickstart

Your first passport

One authenticated request. The response carries the resolvable Digital Link and the carrier payload you print or encode.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "09506000134352",
    "productGroup": "textiles",
    "level": "model",
    "record": {
      "name": "Merino Crew Knit",
      "materials": [
        { "name": "merino wool", "share": 0.82, "certification": "RWS" },
        { "name": "recycled polyamide", "share": 0.18 }
      ]
    }
  }'

Illustrative request shape. The API reference carries the authoritative schema and error contract.

Reference

Where to go next

Eight pages cover the whole surface. These are ordered the way an integration usually proceeds.

Integration path

From API key to a resolvable passport

Four steps. The second is the only one that usually takes longer than an afternoon.
  1. 01

    Get a scoped key

    Keys are scoped per environment and per capability, so an issuing service never holds read access to restricted data.

  2. 02

    Map the product record

    Post your product master against its GS1 identifier. The response names the fields the product group still requires.

  3. 03

    Append events and credentials

    Write EPCIS 2.0 events as the item moves; issue credentials for claims that must survive independent scrutiny.

  4. 04

    Resolve and subscribe

    The identifier resolves to the caller-appropriate view, and webhooks notify your systems when anything changes.

Answers

Frequently asked questions

What do I need before I can issue a passport?

An API key, a GS1 identifier for the product, and the product record itself. If you do not yet have GS1 identifiers, that is the first dependency to resolve — they come from your GS1 member organisation, not from us, because the identity has to be globally unique outside our platform.

Is there a sandbox?

Yes. Keys are scoped per environment, so sandbox keys cannot touch production passports and production keys cannot be used accidentally in a test harness. Sandbox passports resolve exactly as production ones do, against a separate resolver hostname.

What are the wire formats?

JSON over HTTPS for the API. Events follow the GS1 EPCIS 2.0 JSON-LD serialisation, and credentials follow the W3C Verifiable Credentials 2.0 data model. Where a standard defines a representation we use it rather than inventing one, which means existing tooling for those standards works against our output.

How should errors be handled?

The API returns conventional HTTP status codes with a structured error body naming the field and the constraint that failed. Validation errors are returned in full rather than one at a time, so a malformed product record surfaces every problem in one response instead of over five round trips.

How do we get support while integrating?

Through the support channel on your account, or via the contact route if you are still evaluating. Integration questions that reveal a gap in the documentation are treated as documentation defects, which is the only way a reference stays accurate as the API grows.

Next step

Issue a passport against your own GTIN

Get a sandbox key, post one product record, and see what resolves from the carrier it returns.

Get an API keyAPI reference

Index

Related reading