Programmatic access to product passports — for webshop/ERP sync and bulk automation.

From the Pro plan

During the open beta the API is available to every beta account — the Pro requirement applies after the beta.

Authentication

Every request authenticates with an API key, in the Authorization header:

Authorization: Bearer vk_<your key>

You create a key under Settings → Developer API. The plaintext key is shown only once, at creation — store it safely. The key grants read/write access to all products in your account, so keep it confidential.

Quick test in the browser

The key goes only in the Authorization header — not as a URL parameter, for security (it would end up in browser history and server logs). Try it for example with curl:

curl -H "Authorization: Bearer vk_<your key>" https://veridyn.eu/api/v1/categories

Key scope

When creating a key you choose a scope: Full (read + write) or Read-only. A read-only key may only call GET — POST/PATCH/DELETE return 403 read_only. Use a read-only key for ERP or display integrations.

Rate limit

Per key, 120–600 requests / minute depending on plan (Pro 120 · Business 300 · Enterprise 600; 300 during the open beta). Every response includes the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix time) headers. Exceeding the limit returns 429 rate_limited with a Retry-After header — wait the indicated time, then retry.

Idempotency

You can add a unique Idempotency-Key header to POST requests. If you resend it with the same key (e.g. after a network error), you get back the original response — no duplicate is created. A replayed response is marked with the Idempotency-Replayed: true header.

OpenAPI

Machine-readable API description (OpenAPI 3.1) — for Postman import and SDK/code generation:

https://veridyn.eu/api/v1/openapi.json

⚡ Interactive API reference

Browsable, searchable endpoint reference — rendered directly from the spec above.

DPP vocabulary (JSON-LD namespace)

The machine-readable passport is JSON-LD: standard fields come from schema.org, DPP-specific fields from the dpp: namespace. That namespace is resolvable — open it to see what every field means, or send Accept: application/ld+json to get the machine-readable @context document.

https://veridyn.eu/ns/dpp/v1/

A single passport as data: its public URL with ?format=jsonld (or an Accept: application/ld+json header).

Postman collection

A ready-to-import collection with pre-set variables and example requests. After importing, just fill in the base_url and api_key collection variables.

⬇ Download Postman collection

Generate your own SDK

From the OpenAPI spec you can generate an official client in any language with openapi-generator — no hand-maintained SDK, always up to date. E.g. PHP:

npx @openapitools/openapi-generator-cli generate \
  -i https://veridyn.eu/api/v1/openapi.json \
  -g php -o ./veridyn-sdk

The -g value can be typescript-fetch, python, java and many more.

Quickstart (code)

PHP

$ch = curl_init('https://veridyn.eu/api/v1/products?limit=5');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer vk_...'],
]);
$products = json_decode(curl_exec($ch), true)['data'];

JavaScript (fetch)

const res = await fetch('https://veridyn.eu/api/v1/products?limit=5', {
  headers: { 'Authorization': 'Bearer vk_...' }
});
const { data } = await res.json();

Base URL

https://veridyn.eu/api/v1

Responses are application/json, UTF-8 encoded.

Sandbox (test account)

Integrations are not built against a live account. Under Settings → Sandbox you can request a separate test account with its own API key: same API, same schemas, fully isolated from your live data.

• Same base URL and authentication — only the key differs. Code written against the sandbox runs unchanged in production.
• Test passports are marked: a TEST banner on the page and noindex in the head — trial data cannot appear in search results as a real product passport.
• No outbound call with legal effect is made: neither EU registry notification nor a copy to your backup provider. Webhooks do fire — so you can watch the flow on your own test endpoint.
• Test data can be wiped with one button (keys are kept), so every trial can start from a clean slate.
• The sandbox mirrors your plan — what you can do live, you can do in the test account.

Endpoints

Method	Path	Description
GET	/categories	Available product categories.
GET	/schema/{category}	The category's full field list — required + optional, type, enum, localized fields.
GET	/products	List of products (summary). Parameters: q, status, page, limit — or updated_since and cursor for changes-only sync.
POST	/products	New product passport. Body: { category, data }.
POST	/products:batch	Bulk create — up to 500 products per request. Body: { category, products: [ … ], on_duplicate? }. Returns a per-row report.
GET	/products/{id}	A product's full data + passport URL.
PATCH	/products/{id}	Update (partial) — creates a new version. Body: { data, change_type? }. change_type is optional: correction (the model held wrong data → already-issued batch/unit passports become out of date and can be refreshed) or change (the product changed from a given date → earlier units keep their correct data and are not overwritten).
GET	/products/{id}/qr	QR code (SVG) for the public passport.
GET	/events	History of outgoing webhook events (?after_id= & limit=) — for de-duplication and catching up on missed events.
GET	/products/{id}/children	List of the batch/unit child passports.
POST	/products/{id}/children	Batch/unit passport. Single: { level, lot|serial, data } · bulk: { level, items:[…] } (max 500). Inherits the parent's data.
PATCH	/products/{id}/children	Bulk update of child passports (max 500): { items:[{ serial|lot|id, data }] }. For live BMS data — with a per-row report.
POST	/products/{id}/archive /products/{id}/restore	Archive and restore. Deliberately not a PATCH: a visibility change is not a data change, so it creates no empty version in the change history. No body needed.
GET	/products/{id}/versions /products/{id}/versions/{no}	The change history: the list of versions, or a given version's field-level diff (what changed, from what to what).
GET POST DELETE	/products/{id}/grants /products/{id}/grants/{gid}	Expiring access links for an authority / a party with legitimate interest — reaching confidential fields without a login. DELETE revokes one.
GET POST DELETE	/products/{id}/documents /products/{id}/documents/{docId}	Certificates and documents. Upload in base64 (PDF, PNG, JPEG, WebP), download the file, delete. The GET with a document id returns the file, not JSON.
GET POST	/supplier-requests	Supplier data requests: list and create. The response contains the supplier link.
GET POST DELETE	/supplier-requests/{rid} /supplier-requests/{rid}/merge	One request with its submitted values, merging the submission (new product version), or cancelling it.
POST	/eo/token	A short-lived JWT for the standards-based economic operator interface. Body: { ttl? }.
GET	/products/{id}/scans	Per-product scan summary: total, unique, byCountry, byDevice. Parameter: days=7|30|90|365.
GET	/products/{id}/batterypass	The battery passport in CEN-CENELEC JTC24 (BatteryPass) form. Parameter: profile=feb27|full — feb27 is the narrower set binding from 2027-02-18, full is the complete data model. Battery category only.
GET	/scans	Tenant-wide scan summary: the above + byCategory, byLevel.

What to send? (required vs. optional)

Every category has a required core — without it, schema validation rejects the request (422). All other fields are optional, but you can send them in the same data object anytime (more data = a better passport and more future-proof compliance). The exact, machine-readable field list is returned by /schema/{category} — with required: true/false, type, enum and localized markers.

curl https://veridyn.eu/api/v1/schema/textile \
  -H "Authorization: Bearer vk_<key>"

All fields by category

✓ = required · — = optional · ↳ nested sub-field · 🌐 per-language (localized) · 🔒 visible only at authority level. This list is generated from the schema — always up to date.

Languages

The languages field (e.g. ["hu","en"]) declares which languages have free-text content. The localized fields (care, end-of-life… — "localized": true in /schema) must be filled only in the first (primary) language; the rest are optional, falling back to an available language if missing. The passport's UI labels are translated to 24 languages automatically, independently of this.

Examples

Bulk load from the ERP

curl -X POST https://veridyn.eu/api/v1/products:batch   -H "Authorization: Bearer vk_<key>"   -H "Content-Type: application/json"   -H "Idempotency-Key: erp-2026-09-24-001"   -d '{
    "category": "battery",
    "on_duplicate": "skip",
    "products": [
      { "sku": "VE60-001", "productName": "PowerCell 60", "...": "..." },
      { "sku": "VE60-002", "productName": "PowerCell 60 XL", "...": "..." }
    ]
  }'

The response is a per-row report: created / updated / exists (SKU already present) / invalid (with the errors) / plan_limit. Partial success is normal — a bad row does not stop the others.

The Idempotency-Key header removes the risk of retries: after a timeout, repeating the request with the same key returns the earlier response instead of creating everything twice.

Create a product

curl -X POST https://veridyn.eu/api/v1/products \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "textile",
    "data": {
      "productName": "Organic cotton tee",
      "sku": "TEE-001",
      "brandName": "Lumora",
      "languages": ["hu","en"],
      "fiberComposition": [{"fiber":"pamut","percentage":100}],
      "countryOfManufacture": "PT",
      "careInstructions": {"hu":"Mosás 30 °C","en":"Wash at 30 °C"},
      "repair": {"repairable": true, "sparePartsAvailable": false},
      "endOfLife": {
        "recyclingInstructions": {"hu":"Textilgyűjtő","en":"Textile bin"},
        "disposalInstructions": {"hu":"Ne a kukába","en":"Not household waste"}
      },
      "economicOperator": {
        "role":"manufacturer","legalName":"Lumora Kft.","address":"Budapest",
        "country":"HU","contactEmail":"[email protected]"
      }
    }
  }'

Response (201):

{
  "data": {
    "id": "a1993ef7-7562-43bb-92ff-eb63f02dcde9",
    "category": "textile",
    "status": "active",
    "version_no": 1,
    "passport_url": "https://veridyn.eu/<account>/p/a1993ef7-…",
    "qr_url": "https://veridyn.eu/api/v1/products/a1993ef7-…/qr",
    "data": { "productName": "Organic cotton tee", … }
  }
}

List

curl https://veridyn.eu/api/v1/products?limit=25 \
  -H "Authorization: Bearer vk_<key>"

Get a product

curl https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<key>"

Update (new version)

curl -X PATCH https://veridyn.eu/api/v1/products/{id} \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"data": {"recycledContentPercentage": 30}}'

The provided fields are merged onto the existing data (partial update), then validated, and a new, retained version is created — the full change history is preserved.

Batch and unit passports (serialisation)

Create batch or unit passports under a model; the child inherits the parent's data — you pass only the instance-specific fields (lot/serial). Many at once (items[], max 500); the response reports success/error per item.

curl -X POST https://veridyn.eu/api/v1/products/{id}/children \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"level":"item","items":[{"serial":"SN-0001"},{"serial":"SN-0002"}]}'

The {id} may be a model or a batch. POST to a batch id with level:"item" and the unit is created under that batch, inheriting its lot — its GS1 link is then …/10/lot/21/serial rather than …/21/serial. This is how the full model → batch → unit chain is built.

Writing live data back in bulk

Some unit-level fields are live data: a battery's SoH, cycle count and remaining capacity come from the BMS. You do not have to write these back one by one — a single call updates up to 500 child passports. Targets are identified by serial, lot or id, so what your MES already knows is enough; you need not store our internal identifier.

curl -X PATCH https://veridyn.eu/api/v1/products/{id}/children \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"change_type":"change","items":[
        {"serial":"SN-0001","data":{"stateOfHealth":97,"fullCycleCount":412}},
        {"serial":"SN-0002","data":{"stateOfHealth":95,"fullCycleCount":508}}
      ]}'

The response is a per-row report: updated · unchanged · not_found · ambiguous (the serial is not unique under the parent) · validation. An unchanged row creates no new version — so a daily fleet sync does not pad the change history with empty versions. change_type applies to the whole batch: a BMS refresh is a change (the earlier value was true at its time), not a correction.

Scan analytics

Aggregated QR-scan statistics — per product or account-wide — broken down by country and device. Privacy: no raw IP; unique visitors are an anonymous hashed estimate.

curl "https://veridyn.eu/api/v1/products/{id}/scans?days=30" \
  -H "Authorization: Bearer vk_<key>"

{
  "data": {
    "product_id": "a1993ef7-…",
    "range_days": 30,
    "total": 189, "unique": 142,
    "byCountry": { "HU": 142, "DE": 38, "AT": 9 },
    "byDevice":  { "mobile": 168, "tablet": 9, "desktop": 12 }
  }
}

Incremental sync (changes only)

An ERP cannot re-read the whole passport inventory every night: as the catalogue grows, so does the run time. With the updated_since parameter you get back only what changed since that moment — and the list then returns every level (model, batch, unit), because an MES also synchronises the unit passports.

curl "https://veridyn.eu/api/v1/products?updated_since=2026-09-24T00:00:00Z&limit=100" \
  -H "Authorization: Bearer vk_<key>"

{
  "data": [
    { "id": "a1993ef7-…", "name": "VE60 EV modul", "status": "active",
      "updated_at": "2026-09-24T08:11:32+00:00", "passport_url": "…" },
    { "id": "c7d10b42-…", "name": "VE60-000418", "status": "archived",
      "updated_at": "2026-09-24T14:02:07+00:00", "passport_url": "…" }
  ],
  "per_page": 100,
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0yNCAxNDowMjowN3xjN2QxMGI0Mi0…"
}

The sync response has no page or total — instead there is has_more and next_cursor. You request the next page by passing the received next_cursor back unchanged: ?cursor=…. The cursor is opaque: do not decode or construct it — a hand-made value is rejected with 422 bad_cursor.

curl "https://veridyn.eu/api/v1/products?cursor=MjAyNi0wOS0yNCAxNDowMjowN3xjN2QxMGI0Mi0…" \
  -H "Authorization: Bearer vk_<key>"

Why a cursor and not a page number

Because page-number pagination silently skips rows. The list is ordered by modification time: while you are asking for page 2, an already-seen product is updated, jumps to the front, and everything behind it shifts back one — the row that was exactly on the page boundary never reaches you. Meanwhile the client believes it received everything. A cursor points at the specific last row you processed, not at a position, so this cannot happen. (For timestamps landing in the same second the internal identifier breaks the tie — on an import that affects dozens of rows.)

Archived passports appear too — that is the point

Archiving does not remove a product from the sync window: it comes back with status: "archived". That is the tombstone — this is how your system knows to drop it from its own list. If archived rows were filtered out, the client would keep them as active forever.

Recommended flow: store the last next_cursor; the next run starts from it and pages until has_more is false. For the initial (full) load use updated_since=1970-01-01T00:00:00Z — from then on only changes travel over the wire.

Two things your client should expect

1. The most recent second is held back. The modification timestamp has one-second resolution, so the list only serves already closed seconds: a passport you just saved typically appears in the sync list 1–2 seconds later. This is deliberate. Without it the cursor could step into a second that is still open, and a passport saved later within that same second would never be delivered — not delayed, lost, and silently so.

2. An empty page still carries a cursor. If nothing changed, data is empty and has_more is false — but next_cursor is still not empty, and it has moved forward. Always store it: the cursor advances even when nothing changed.

Certificates and documents

The declaration of conformity, the test report and the safety data sheet live in PDF — and they usually originate in a document management system or in correspondence with a lab, not in a browser tab. The file content therefore travels in the request body as base64:

curl -X POST https://veridyn.eu/api/v1/products/{id}/documents \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"filename":"ce-tanusitvany.pdf","tier":"public","label":"CE","content_base64":"JVBERi0xLjQK…"}'

The type is decided by the content, not the file name. An extension can lie — and someone lying deliberately is counting on exactly that — so we detect the type from the bytes. If it is not PDF, PNG, JPEG or WebP, the answer is 415 bad_type and nothing is stored. The stored file is named by our identifier; the submitted filename is only a display label.

The tier says who may see it: public (shown on the public passport too), legitimate_interest or authorities — the same ranking as the schema fields use. An unknown value falls back to the narrowest, public, so for a confidential document always set it.

The size limit is 8 MB for the decoded file. Base64 makes the request body larger than that (about 4/3), and if it exceeds the server's body limit, the body never arrives — that returns 413 payload_too_large, and we name the server's actual limit in it so you are not left debugging your own code.

You can also ask for the actual maximum before uploading anything: GET /health (it works without a key) returns limits.document_upload_max_bytes, the narrower of the two. It is worth fetching once at start-up.

curl https://veridyn.eu/api/v1/health

{
  "status": "ok",
  "limits": {
    "document_max_bytes": 8388608,
    "request_body_max_bytes": 8388608,
    "document_upload_max_bytes": 6165626,
    "bulk_max_items": 500
  }
}

The download returns the file itself, not JSON — with its own content type; ?dl=1 serves it as an attachment. A DELETE removes it from disk as well.

curl https://veridyn.eu/api/v1/products/{id}/documents/42?dl=1 \
  -H "Authorization: Bearer vk_<key>" -o tanusitvany.pdf

Supplier data requests

You do not know all of the passport data yourself: the fibre composition comes from the mill, the cell provenance from the cell maker. You start a request for the specific fields, and the supplier fills in their part via a login-free link — you need not give them an account. This has long existed in the UI but not in the API: a procurement system could upload 500 passports, yet had to start the 500 data requests by hand.

curl -X POST https://veridyn.eu/api/v1/supplier-requests \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"a1993ef7-…","email":"[email protected]",
       "fields":["fiberComposition","countryOfManufacture"],
       "message":"For the next shipment, please.","lang":"en"}'

{
  "data": {
    "id": 17, "status": "pending", "email": "[email protected]",
    "fields": ["fiberComposition", "countryOfManufacture"],
    "expires_at": "2026-10-25 09:14:02",
    "link": "https://veridyn.eu/supplier.php?token=9f3c…",
    "emailed": true
  }
}

The link is always in the response — even when we send the email. A machine integration usually writes to the supplier from its own mail system (own template, own sender, own tracking); in that case send_email: false switches off our sending and you deliver the link yourself. `fields` are the category schema's field keys (GET /schema/{category}); internal fields cannot be delegated. The link expires after 30 days.

Reviewing and merging the submission

Until the supplier fills anything in, the request is pending. After submission it is submitted, and the detail endpoint shows what they wrote — with both the raw field key and a human field name, so an approval UI need not know the schema. Merging is a separate step: incoming data does not enter the product automatically.

curl https://veridyn.eu/api/v1/supplier-requests/17 \
  -H "Authorization: Bearer vk_<key>"

curl -X POST https://veridyn.eu/api/v1/supplier-requests/17/merge \
  -H "Authorization: Bearer vk_<key>"

Merging transfers only the REQUESTED fields. The supplier (or anyone who knows the token) may send more, but anything you did not ask for does not touch the product — whoever you only asked about the country of manufacture cannot rewrite your brand name.

If the merged data is invalid (422 validation), the product stays untouched and the request is not closed: you clarify it with the supplier and retry. On success a new version is created and a product.updated webhook goes out marked source: "supplier_merge" — so your own system can see it was a submission, not your own edit.

Archiving and restoring

When a product is discontinued you archive it — but we do not delete the passport: the QR code and link keep working, and the passport is shown as "archived". Legal retention requires this: the passport of a unit already on the market must stay alive even after you stop making the model.

curl -X POST https://veridyn.eu/api/v1/products/{id}/archive \
  -H "Authorization: Bearer vk_<key>"

curl -X POST https://veridyn.eu/api/v1/products/{id}/restore \
  -H "Authorization: Bearer vk_<key>"

No body needed. The operation creates no new version: a visibility change is not a data change, and a version with an empty diff would only add noise to the change history — which is also why this is a separate endpoint rather than a PATCH. A webhook is fired: product.archived and product.restored.

It does not free up quota: the plan's model counter includes archived passports, so archiving does not make room for a new one, and restoring does not consume any.

Change history (versions)

Every PATCH creates a new, retained version, and the chain is hash-sealed — it cannot be rewritten after the fact. The history is machine-readable too: the list returns the versions, and /versions/{no} returns which field changed, from what to what.

curl https://veridyn.eu/api/v1/products/{id}/versions \
  -H "Authorization: Bearer vk_<key>"

curl https://veridyn.eu/api/v1/products/{id}/versions/3 \
  -H "Authorization: Bearer vk_<key>"

Both are reads, so a read-only key is enough — you need not grant write access to an auditing system. The change_type is visible as well: a correction fixes wrong data (already-issued unit passports become out of date), while a change is a real product change from a given date (earlier units keep their correct data).

Access links (authority, legitimate interest)

The public passport shows the public fields. The regulation, however, requires broader access for the market-surveillance authority and parties with legitimate interest (a recycler or repairer, say). That is what expiring access links are for: they open without a login, for a single passport, and go quiet on their own at expiry — you need not hand out accounts.

curl -X POST https://veridyn.eu/api/v1/products/{id}/grants \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"tier":"authority","label":"NKFH 2026/114","expires_in_days":30}'

{
  "data": {
    "id": 42, "tier": "authority", "label": "NKFH 2026/114",
    "status": "active", "expires_at": "2026-10-25 09:14:02",
    "use_count": 0, "last_used_at": null,
    "token": "9f3c…",
    "passport_url": "https://veridyn.eu/acme/p/a1993ef7-…?grant=9f3c…",
    "history_url":  "https://veridyn.eu/history.php?id=a1993ef7-…&grant=9f3c…"
  }
}

Field	Meaning
tier	legitimate_interest or authority. No other tier can be granted (422 bad_tier): the owner tier is your own account and cannot be handed out as a link.
expires_in_days	Optional — and leaving it out means a permanent link. An authority inspection is finite, so it is worth always setting; after expiry the link returns 410.
label	Free text: whom you gave it to. Visible only to you, not to the recipient.
history_url	Filled in only at authority tier: an authority may also open the full change history; a legitimate-interest party may not.
use_count	How many times it was opened. A freshly issued link is always 0 — issuing is not a use.

The GET lists the live links of that passport, and DELETE /products/{id}/grants/{gid} revokes one immediately — the token then returns 410.

Schema version: when you need to touch your integration

A category's field list moves with the legislation. Until now nothing signalled that a schema had changed — integrations broke silently. So GET /schema/{category} now returns a version and an ETag:

curl -i https://veridyn.eu/api/v1/schema/battery \
  -H "Authorization: Bearer vk_<key>"

HTTP/1.1 200 OK
ETag: "battery.1.0.02894917d482"
X-DPP-Schema-Version: 1.0
Cache-Control: public, max-age=3600

The ETag is built from the machine contract: field names, types, whether they are required, their enum values and access tiers. So what does not change it: labels, help text, translations. You therefore get no false alarm just because a field's wording was made more precise.

curl -i https://veridyn.eu/api/v1/schema/battery \
  -H "Authorization: Bearer vk_<key>" \
  -H 'If-None-Match: "battery.1.0.02894917d482"'

HTTP/1.1 304 Not Modified

Put the ETag into your bootstrap script or nightly job: as long as you get a 304, the contract holds and there is nothing to do. If a 200 arrives, the response's version, revised and contract_hash fields show what moved.

If a backwards-incompatible change is being prepared for a category, the response also carries Deprecation and Sunset headers (RFC 8594), the Sunset being the earliest date the old shape goes away. By default neither header appears — if you see one, you have a real deadline.

Response & errors

Success: the payload is under the data key. On error:

{ "error": "Invalid data.", "code": "validation", "errors": [ … ] }

HTTP	code	Meaning
401	unauthorized	Missing/invalid API key.
403	plan_required	The API is available from the Pro plan (during the open beta, every beta account can use it).
404	not_found	No such product / route.
409	gtin_taken	The GTIN is already taken.
422	gtin_not_yours	The GTIN falls outside your account's GS1 company prefix (Settings → GS1 company prefix). Only occurs if you have set a company prefix.
403	plan_limit	You reached the level's quota (plan + extra). In bulk calls, the overflowing items go into errors.
422	validation	Invalid data (details in errors).
403	read_only	You attempted a write with a read-only key (POST/PATCH/DELETE).
429	rate_limited	You exceeded the per-minute request quota. The Retry-After header says how long to wait.
400	bad_json	The request body is not valid JSON. The API accepts a JSON body only (Content-Type: application/json).
413	too_big	The uploaded document exceeds the allowed size. GET /health returns the actual limit in limits.document_upload_max_bytes.
413	payload_too_large	The request body never arrived — it hit the server's post_max_size limit. The JSON is not at fault, the size is.
422	bad_cursor	The cursor is not a next_cursor we issued. Pass it back unchanged — the cursor is opaque.
422	bad_tier	A link cannot be issued at this access tier (only legitimate_interest and authority).
501	needs_migration	The feature requires a database update that is not yet active. We deliberately fail rather than return partial data — tell us and we will enable it.

BatteryPass Economic Operator API

The /api/v1 above is our interface. Alongside it we operate a standards-based one: the endpoints of the CEN-CENELEC JTC 24 lifecycle API (EN 18222), “Digital Product Passport – Life Cycle API v1.1”, in the language the rest of the battery ecosystem speaks. Use it when your partner expects a standard integration rather than our API.

Conformance: the interface passes all 11 tests of the official BatteryPass-Ready conformance suite (read by DPP ID and by product ID, data-element read, access-rights filtering, withdrawn passport, update, adding and deleting an attribute, permission check, placing on the market). The suite tests a live system, not an uploaded file.

Base URL and authentication

https://veridyn.eu/eo — authentication: Authorization: Bearer {JWT}. The token carries a role (public, purchaser, authority, economic_operator…), and the response is filtered field by field accordingly — by the same machinery that filters the public passport. Only the economic operator can write.

Where the token comes from

You request the token with your own developer key — there is no separate registration:

curl -X POST https://veridyn.eu/api/v1/eo/token \
  -H "Authorization: Bearer vk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"ttl":3600}'

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs…",
    "token_type": "Bearer",
    "role": "economic_operator",
    "expires_in": 3600,
    "expires_at": "2026-09-25T11:14:02+00:00",
    "api_base": "https://veridyn.eu/eo"
  }
}

The token is scoped to the key's account — we deliberately do not take the tenant from the request, so you cannot request a token for someone else's passports. The only role available is economic_operator: the “this is my product” role. authority or recycler speak on another party's behalf and nobody may grant those to themselves — that is what expiring access links are for.

The ttl is in seconds, between 5 minutes and 24 hours (default 1 hour). The cap is deliberate: a JWT is self-contained and we keep no blacklist, so a lost long-lived token could not be revoked. Short token plus re-request is the right pattern. A read-only key mints no token (403 read_only), because the economic-operator role also authorises writes.

Method	Path	Description
POST	/dpps	New passport from the submitted JTC24 document. Response: the identifier (string), 201.
GET	/dpps/{dppId}	Read by DPP identifier.
PATCH	/dpps/{dppId}	Partial update (RFC 7396) — creates a new version. A null value deletes the field.
DELETE	/dpps/{dppId}	Withdrawal. The passport is retained (authorities may request it retrospectively) but returns 404 on this interface.
GET/PATCH	/dpps/{dppId}/elements/{path}	Read/update a single data element by dotted path.
GET/PATCH	/dpps/{dppId}/collections/{group}	A data group (e.g. performanceAndDurability).
GET	/dppsByProductId/{productId}	The active version by product identifier.
GET	/dppsByProductIdAndDate/{productId}	The version valid at a given point in time. Parameter: date.
POST	/dppsByProductIds	Bulk identifier resolution. Parameters: limit, cursor.

Backup and registry: under (EU) 2023/1542 the passport data must also be stored with an independent provider, and placing on the market must be reported. If a backup provider is configured for the account, a copy is sent automatically after every create and update — and every call leaves an auditable trace.

Webhooks

Under Settings → Webhooks you register an HTTPS URL. When a product passport is created / updated / archived, Veridyn POSTs a signed JSON to that URL — so your system is notified in real time, without polling.

Events

product.created · product.updated · product.archived · product.restored · children.updated · scan.milestone · scan.clone_suspected

The children.updated event covers a bulk update of child passports and is deliberately a single, aggregate event — not one per row. Data: { parent_id, category, count, items }, where items lists the child passports that actually changed as { id, serial, lot } (unchanged rows are excluded). The per-row detail is in the call's response, not in the webhook — it goes to the caller who initiated the update.

The scan.milestone fires when a passport's scan count crosses a milestone (10, 50, 100, 250, 500, 1000, …) — e.g. "your passport was opened 1000 times". Data: { product_id, count, milestone }.

The scan.clone_suspected flags possible counterfeiting: a unique (serialised) passport was scanned unusually often and from many different countries/devices — which may indicate a copied QR code. Data: { product_id, count, countries, unique_devices }.

Delivery

POST https://your-system.example/veridyn-webhook
Content-Type: application/json
X-Veridyn-Event: product.updated
X-Veridyn-Event-Id: evt_9f21c4a08b73d5e6f1a20c44
X-Veridyn-Timestamp: 2026-07-02T13:19:11+00:00
X-Veridyn-Signature: sha256=<hmac>

{
  "event_id": "evt_9f21c4a08b73d5e6f1a20c44",
  "event": "product.updated",
  "data": { "id": "a1993ef7-…", "category": "textile", "version_no": 2 },
  "sent_at": "2026-07-02T13:19:11+00:00"
}

Signature verification

The X-Veridyn-Signature is the HMAC-SHA256 of the raw body with the webhook secret (shown in Settings). Verify it — e.g. in PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_VERIDYN_SIGNATURE'] ?? '')) {
    http_response_code(401); exit; // invalid signature
}

Respond with a 2xx status. If delivery fails (non-2xx / timeout), we automatically retry with exponential backoff (about 1 min → 5 min → 30 min → 2 h → 6 h, up to 6 attempts), giving up on persistent failure (after about 8.5 hours). The status of the last delivery is shown in Settings, where it can also be resent manually.

De-duplication and catching up on missed events

Retrying means the same event may arrive more than once — for example if your response times out although your processing already completed. That is why every event carries an event_id: store the ones you have processed and drop any identifier you have already seen. This matters most for a bulk children.updated event, where a single duplicate would mean processing 500 rows twice.

If your system was unreachable for a long time (maintenance, a weekend outage), the 6 attempts can run out and the event would be lost. That is what GET /events is for: it returns every outgoing event in chronological order, together with its delivery status. Remember the last id you processed and continue from there — not by page number, because new events may appear in the meantime.

curl "https://veridyn.eu/api/v1/events?after_id=1487&limit=100" \
  -H "Authorization: Bearer vk_<key>"

{
  "data": [
    {
      "id": 1488,
      "event_id": "evt_9f21c4a08b73d5e6f1a20c44",
      "event": "product.updated",
      "data": { "id": "a1993ef7-…", "category": "textile", "version_no": 2 },
      "sent_at": "2026-07-02T13:19:11+00:00",
      "delivery": { "status": "failed", "attempts": 6, "http_status": 502, "url": "https://…" }
    }
  ],
  "after_id": 1487,
  "next_id": 1488
}

The delivery.status is delivered (sent successfully), pending (still retrying) or failed (given up). The event is listed even if delivery never succeeded — that is precisely what makes catching up possible.

← Settings / API keys