Skip to main content

Integration API: build and manage passports from your own systems

The Integration API is generally available. ERP, PLM and other systems can create, complete, submit and withdraw Digital Product Passports over HTTP, and manage their own API keys, webhooks and field mappings.

Build a passport​

  • Discover. GET /industries, GET /categories and GET /categories/{code}/schema show which fields a category requires, so you can map your own columns against them. GET /suppliers lists your owned or linked suppliers.
  • Author. Create a draft, then send fields in batches with PUT /products/{id}/form-data. Each field is validated, and errors name the field, never the value you sent.
  • Complete. Add traceability links, components and GS1 prefixes, and attach evidence documents.
  • Check and submit. GET /products/{id}/readiness returns the completeness and compliance figures the operator wizard shows, with the gaps. Submit the draft for review; a person on your team publishes it in the portal, so the published record carries their attribution.
  • Withdraw. POST /products/{id}/withdraw withdraws a published passport. It stays available with a withdrawal notice.

Manage your integration​

  • ERP field mapping. Map your column names to Traceable field IDs, lint a mapping, and apply it with ?mapping=<id> on writes.
  • Sandbox mode. Build with a pk_test_ key and send X-Traceable-Mode: test; sandbox data never touches a real passport. See Sandbox mode.
  • Key management. Create, rotate and revoke keys under /api/v1/keys, and restrict a key to IP ranges. This needs the privileged keys:admin scope.
  • Signed webhooks. Receive signed events with retries, and review delivery history under /webhook-endpoints.
  • Data-subject endpoints. Handle access, erasure and export requests under /api/v1/gdpr/* with the privileged gdpr:admin scope.
  • Schema versioning. GET /categories/{code}/diff and GET /products/{id}/schema-compatibility show what changed between schema versions.
  • Platform endpoints. GET /openapi.json and GET /health are unauthenticated; GET /meta shows a key's scopes and rate-limit policy.

Access​

Operators create an API key in Settings, API keys. Thirteen scopes can be granted to a key, such as dpp:read, dpp:draft:write, dpp:submit and dpp:withdraw; there is no publish scope. Every response carries x-traceable-api-version and x-traceable-request-id, and authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Start with the Integration API overview, the availability matrix and the API reference.