CirculeID

Examples

The five requests an integration actually makes

Issue a passport. Append an event. Sign a supplier claim. Verify one. Serve a scan. Most integrations are these five, repeated — everything else is mapping.

Get a sandbox keyAPI reference
Start with
Issue + append
Add later
Signed claims
Environment
Sandbox first

Definition

What does a typical passport integration actually do?

Five operations, repeated. Issue a passport against a GS1 identifier. Append EPCIS 2.0 events as the product moves. Collect signed claims from suppliers. Verify a claim you were presented. And serve the public view when someone scans the data carrier on the product.

The volume is dominated by the first two. The difficulty is dominated by the third, which is a supplier relationship problem rather than a technical one.

01

Issue a passport

Post the product record against its GS1 identifier. The response carries the resolvable Digital Link, the carrier payload, and the gap report for the product group.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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 }
      ],
      "carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
    }
  }'

02

Append a supply chain event

EPCIS 2.0 in its JSON-LD serialisation. What object, when, where, and which business step — the four dimensions every event answers.
POST /v1/events
curl https://api.circuleid.com/v1/events \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -d '{
    "type": "ObjectEvent",
    "action": "OBSERVE",
    "eventTime": "2026-03-14T09:22:00+01:00",
    "epcList": ["urn:epc:id:sgtin:0950600.013435.SN8817403"],
    "bizStep": "urn:epcglobal:cbv:bizstep:commissioning",
    "disposition": "urn:epcglobal:cbv:disp:active",
    "bizLocation": { "id": "urn:epc:id:sgln:0950600.00001.0" }
  }'

03

Sign a supplier claim

Issued by the supplier under their own decentralized identifier, so the claim carries its author. This is what turns a stored figure into evidence.
POST /v1/credentials
curl https://api.circuleid.com/v1/credentials \
  -H "Authorization: Bearer $SUPPLIER_API_KEY" \
  -d '{
    "type": "RecycledContentCredential",
    "issuer": "did:web:mill.example.com",
    "subject": "01/09506000134352",
    "validUntil": "2027-03-14T00:00:00Z",
    "claim": {
      "material": "polyamide",
      "recycledShare": 0.18,
      "basis": "mass",
      "chainOfCustody": "mass-balance"
    }
  }'

04

Verify a claim you were presented

Verification checks the signature and the revocation status. It does not require CirculeID — this endpoint is a convenience, not a dependency.
POST /v1/credentials/verify
curl https://api.circuleid.com/v1/credentials/verify \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -d '{ "credential": { /* the credential as presented */ } }'

# {
#   "verified": true,
#   "issuer":   "did:web:mill.example.com",
#   "issuedAt": "2026-03-14T09:31:02Z",
#   "status":   "active"        # "revoked" fails verification
# }

05

Serve a scan

The public path. No key, no account, and the same response for every anonymous caller — which is why it can be cached at the edge.
GET /01/{gtin}
# What the phone requests when a consumer scans the carrier:
curl https://id.circuleid.com/01/09506000134352 \
  -H "Accept: application/json"

# A browser gets the rendered public passport instead.
# A verified recycler presenting a credential gets the treatment tier
# from the same URL — the resolver decides, not the caller.

Patterns

Where each one usually lives

The same five operations, placed in the systems that typically own them.

  • Issuing pipeline

    A scheduled job reading PLM and issuing passports for the next production run.

  • Event ingestion

    A service translating WMS and MES messages into EPCIS events as they occur.

  • Supplier portal

    Where tier-two suppliers submit and sign the claims you cannot assert yourself.

  • Storefront

    Reading the public tier to show substantiated sustainability data on a listing.

  • The carrier itself

    No code of yours at all — the resolver serves the scan directly.

  • Take-back intake

    Reading the treatment tier at a returns or recycling facility line.

Answers

Frequently asked questions

Which example should I start from?

Issuing a passport, then appending an event. Those two cover the majority of an integration’s traffic and force you to settle the identity model — model, batch or item — which is the decision everything else depends on and the hardest one to change later.

Do I need to handle credentials on day one?

No. A passport with unsigned data is still a working passport; it simply cannot demonstrate who asserted each figure. Most programmes issue first and add signed supplier claims as suppliers onboard, which is also the order supplier engagement realistically allows.

What does the consumer actually receive from a scan?

The public tier of the passport, resolved from the GS1 Digital Link identifier in the carrier, rendered as a page for a browser or returned as JSON to a system that asks for it. No authentication, no account, and no profile of the person scanning.

Can we test without touching production?

Yes. Sandbox keys resolve against a separate hostname, and sandbox passports behave exactly like production ones. Because a production passport is a long-lived public artefact, the separation is enforced rather than conventional — a sandbox key simply cannot reach production.

Next step

Run the first two against a sandbox key

Issue one passport and append one event. That is enough to settle the identity model, which is the decision everything else rests on.

Get a sandbox keyAPI reference

Index

Related reading