Article 77(1) requires one passport per physical battery. Creating a battery item creates its passport and mints its unique identifier — C- followed by 11 characters — which never changes and is what the QR code resolves.

New passports are drafts: not public, not billed, until you publish them.

Personalise the samples. Paste a test key and every snippet uses it — and your own model and passport ids.

GET/v1/models/{id}/items

read scope

List a model's batteries

A model’s batteries with a derived display status (draft, pending, published, attention, repurposed, waste, recycled) and, for attention, the reasons. counts covers the whole model, not just the page.

This list pages by number. For syncing, prefer the cursor-paginated List passports with model_id.

Parameters5

idstringpathrequired
The model id.
statusstringqueryoptional
Only this display status: draft, pending, published, attention, repurposed, waste or recycled.
qstringqueryoptional
Serial number or identifier, case-insensitive (contains).
pageinteger ≥ 1queryoptional
Page number. Default 1.
pageSizeinteger, 1–200queryoptional
Rows per page. Default 12.

Responses

200OK — One page of batteries.

Errors3

400Validation failed details names each invalid field.
401unauthorized The key is missing, unknown or revoked.
404Not found No model with this id in your organisation.

GET /v1/models/{id}/items

curl "https://dppapi-production.up.railway.app/v1/models/cm1q8x2k40003l70f9a8s7d6e/items?q=C48-2027&pageSize=200" \-H "Authorization: Bearer $DPP_API_KEY"

200 OK · One page of batteries.

{"total": 100,"page": 1,"pageSize": 200,"counts": { "all": 100, "published": 98, "attention": 2 },"items": [{"id": "cm1q8y0bq0005l70fq2r3t4u5","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","dateOfManufacture": "2027-01-15T00:00:00.000Z","placeOfManufacture": "Stuttgart, Germany","identifierOrigin": "MINTED","passportId": "cm1q8y0bq0006l70fx9y8z7w6","publishedAt": "2027-01-15T10:02:11.000Z","registrationId": null,"displayStatus": "published","attentionReasons": []}]}

POST/v1/items

write scope

Create one battery

Creates one battery and its draft passport. Battery-level data points — the Annex XIII 4(a) values measured when the battery is placed on the market — go in fields.

Moving from another provider? Send the identifier already printed on the battery as uniqueIdentifier. It is kept as-is and, because that code already resolves somewhere, the passport is published immediately if your plan allows publishing.

Request body11

modelIdstringrequired
The model this battery belongs to.
serialNumberstring, ≤ 200optional
Your serial number.
dateOfManufacturedateoptional
ISO 8601 date (data point 9).
placeOfManufacturestring, ≤ 300optional
Plant or city (data point 8). Required before publishing.
placedOnMarketAtdateoptional
Defaults to now.
putIntoServiceAtdateoptional
When it went into service, if known.
productionBatchIdstringoptional
Production batch reference.
fieldsobjectoptional
Battery-level data points keyed by API field name.
uniqueIdentifierstringoptional
Only when bringing an identifier from another provider. Omit to have one minted.
foreignResolverUrlURL, ≤ 500optional
Where the imported identifier resolves today.
importedFromstring, ≤ 200optional
Name of the previous provider, kept on the record.

Headers2

Idempotency-Keystringheaderoptional
Optional. A unique string per logical operation (a UUID is ideal). The first response is stored for 24 hours and replayed for retries; see Idempotency.
X-DPP-Dry-Run"true"headeroptional
Optional, live keys. Validate the write in full and store nothing. Test keys always dry-run; see Test keys.

Responses

201Created — The battery with its passport.

Errors7

400Validation failed details names each invalid field.
401unauthorized The key is missing, unknown or revoked.
402plan_upgrade_required Your plan does not allow creating batteries.
403insufficient_scope The key has no write scope.
404Model not found No such model in your organisation.
409identifier_taken The supplied uniqueIdentifier already exists.
422invalid_identifier The supplied uniqueIdentifier breaks the identifier rules; violations lists them.

Webhooks fired

passport.created

Response fields · 201

object

idstring
uniqueIdentifierstring
Immutable, resolvable passport identifier (ISO/IEC 15459).
serialNumberstring | null
dateOfManufacturestring · date-time | null
placeOfManufacturestring | null
fieldsobject
- idstring
- statusstring
  One ofORIGINALREPURPOSEDREUSEDREMANUFACTUREDWASTE
- lifecycleStatestring
- publishedAtstring · date-time | null
- qrResolverUrlstring

POST /v1/items

curl -X POST "https://dppapi-production.up.railway.app/v1/items" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: 7b3e0c52-1f7d-4b8a-9a52-2f0e6d1c9a44" \-d '{"modelId": "cm1q8x2k40003l70f9a8s7d6e","serialNumber": "C48-2027-0101","dateOfManufacture": "2027-01-16","placeOfManufacture": "Stuttgart, Germany","fields": {"measuredCapacityAtPlacing": 15.2,"measuredResistanceAtPlacing": 38}}'

201 Created · The battery with its passport.

{"id": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","uniqueIdentifier": "C-7KQ2M9XHT4R","identifierOrigin": "MINTED","serialNumber": "C48-2027-0101","dateOfManufacture": "2027-01-16T00:00:00.000Z","placeOfManufacture": "Stuttgart, Germany","fields": { "measuredCapacityAtPlacing": 15.2, "measuredResistanceAtPlacing": 38 },"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","status": "ORIGINAL","lifecycleState": "ACTIVE","publishedAt": null,"qrResolverUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"}}

POST/v1/items/batch

write scope

Create many batteries

Creates up to 1,000 batteries in one request, each with its own passport and identifier. Two shapes: count batteries numbered serialPrefix + a four-digit counter (0001, 0002, …), or explicit rows of serials you already have. When both are sent, rows wins — an existing serial is never replaced with a generated one.

The batch is created in one transaction: either every battery is created or none is. Always send an Idempotency-Key, so that a retry after a timeout cannot create the batch twice.

Request body6

modelIdstringrequired
The model.
countinteger, 1–1000optional
How many to create when rows is absent. Default 1.
serialPrefixstring, ≤ 60optional
Prefix for generated serial numbers.
placeOfManufacturestring, ≤ 300optional
Applied to every battery (rows may override).
dateOfManufacturedateoptional
Applied to every battery (rows may override).
rowsarray, ≤ 1000optional
[{ serialNumber, dateOfManufacture?, placeOfManufacture? }].

Headers2

Idempotency-Keystringheaderoptional
Optional. A unique string per logical operation (a UUID is ideal). The first response is stored for 24 hours and replayed for retries; see Idempotency.
X-DPP-Dry-Run"true"headeroptional
Optional, live keys. Validate the write in full and store nothing. Test keys always dry-run; see Test keys.

Responses

201Created — count and every created battery with its passport (abridged to one).

Errors7

400Validation failed details names each invalid field.
401unauthorized The key is missing, unknown or revoked.
402plan_upgrade_required Your plan does not allow creating batteries.
403insufficient_scope The key has no write scope.
404Model not found No such model in your organisation.
409organisation_frozen The organisation is frozen and read-only.
422idempotency_key_reused The Idempotency-Key was already used with a different body.

Webhooks fired

passport.created (one per battery)

Response fields · 201

object

countinteger
- idstring
- uniqueIdentifierstring
  Immutable, resolvable passport identifier (ISO/IEC 15459).
- serialNumberstring | null
- dateOfManufacturestring · date-time | null
- placeOfManufacturestring | null
- fieldsobject
- - idstring
  - statusstring
    One ofORIGINALREPURPOSEDREUSEDREMANUFACTUREDWASTE
  - lifecycleStatestring
  - publishedAtstring · date-time | null
  - qrResolverUrlstring

POST /v1/items/batch

curl -X POST "https://dppapi-production.up.railway.app/v1/items/batch" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: 7b3e0c52-1f7d-4b8a-9a52-2f0e6d1c9a44" \-d '{"modelId": "cm1q8x2k40003l70f9a8s7d6e","placeOfManufacture": "Stuttgart, Germany","dateOfManufacture": "2027-01-15","rows": [{"serialNumber": "SN-000481"},{"serialNumber": "SN-000482"}]}'

201 Created · count and every created battery with its passport (abridged to one).

{"count": 2,"items": [{"id": "cm1q8y0bq0005l70fq2r3t4u5","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "SN-000481","placeOfManufacture": "Stuttgart, Germany","passport": { "id": "cm1q8y0bq0006l70fx9y8z7w6", "publishedAt": null }}]}

GET/v1/items/{id}

read scope

Get a battery

One battery with its model, passport and registration record.

Parameters1

idstringpathrequired
The battery item id.

Responses

200OK — The battery.

Errors2

401unauthorized The key is missing, unknown or revoked.
404Not found No battery with this id in your organisation.

Response fields · 200

object

idstring
uniqueIdentifierstring
Immutable, resolvable passport identifier (ISO/IEC 15459).
serialNumberstring | null
dateOfManufacturestring · date-time | null
placeOfManufacturestring | null
fieldsobject
- idstring
- statusstring
  One ofORIGINALREPURPOSEDREUSEDREMANUFACTUREDWASTE
- lifecycleStatestring
- publishedAtstring · date-time | null
- qrResolverUrlstring

GET /v1/items/{id}

curl "https://dppapi-production.up.railway.app/v1/items/cm1q8y0bq0005l70fq2r3t4u5" \-H "Authorization: Bearer $DPP_API_KEY"

200The battery.

Batteries

List a model's batteries

Parameters5

Responses

Errors3

Create one battery

Request body11

Headers2

Responses

Errors7

Webhooks fired

Response fields · 201

Create many batteries

Request body6

Headers2

Responses

Errors7

Webhooks fired

Response fields · 201

Get a battery

Parameters1

Responses

Errors2

Response fields · 200

Cookie preferences

Necessary

Analytics