On this pageWhat to send
Annex XIII Point 4 makes part of the passport dynamic: state of health, usage and exposure change over a battery’s life. A BMS or fleet gateway keeps them current by appending events.
What to send
Each dynamic data point belongs to an event type. Put the readings of one type, taken at one moment, in one event:
| Field | Unit | Event type | EV | LMT | Industrial |
|---|---|---|---|---|---|
stateOfCertifiedEnergy | % | SOH_READING | Required | — | — |
remainingCapacity | Ah | SOH_READING | — | Required | If applicable |
capacityFade | % | SOH_READING | Required | Required | If applicable |
remainingPowerCapability | W | SOH_READING | — | Required | If applicable |
remainingRoundTripEfficiency | % | SOH_READING | — | Required | If applicable |
selfDischargeEvolution | %/month | SOH_READING | — | Required | If applicable |
ohmicResistance | mΩ | SOH_READING | — | Required | If applicable |
cycleCount | cycles | CYCLE_COUNT | If applicable | If applicable | If applicable |
energyThroughput | kWh | LIFETIME_METRIC | If applicable | If applicable | — |
capacityThroughput | Ah | LIFETIME_METRIC | If applicable | If applicable | — |
stateOfCharge | % | OPERATING_CONDITION | If applicable | If applicable | If applicable |
operatingTemperature | °C | OPERATING_CONDITION | If applicable | If applicable | If applicable |
timeExtremeHighTemp | min | OPERATING_CONDITION | If applicable | If applicable | If applicable |
timeExtremeLowTemp | min | OPERATING_CONDITION | If applicable | If applicable | If applicable |
timeChargingExtremeHighTemp | min | OPERATING_CONDITION | If applicable | If applicable | If applicable |
timeChargingExtremeLowTemp | min | OPERATING_CONDITION | If applicable | If applicable | If applicable |
negativeEvent | text | NEGATIVE_EVENT | If applicable | If applicable | If applicable |
Recording a reading
Temperature exposure since the last report
curl -X POST "https://dppapi-production.up.railway.app/v1/passports/cm1q8y0bq0006l70fx9y8z7w6/events" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: bms-C-7KQ2M9XHT4R-2027-06-02T07:30Z-oc" \-d '{"eventType": "OPERATING_CONDITION","payload": {"operatingTemperature": 31.5,"timeExtremeHighTemp": 42,"timeExtremeLowTemp": 0,"timeChargingExtremeHighTemp": 5,"timeChargingExtremeLowTemp": 0}}'Lifetime counters
curl -X POST "https://dppapi-production.up.railway.app/v1/passports/cm1q8y0bq0006l70fx9y8z7w6/events" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-d '{"eventType": "LIFETIME_METRIC","payload": {"energyThroughput": 2140.5,"capacityThroughput": 44600}}'Cadence and volume
- The passport is a record, not a time-series database. Report on a meaningful cadence — daily, per charging session, or on change — not every BMS sample.
- With 600 requests a minute per key, one gateway can update 864,000 passports a day with one event each. For larger fleets, batch readings with `POST /passports/import-updates`: up to 1,000 batteries per request, matched by identifier or serial, each reading recorded under its own event type.
- Derive the idempotency key from the battery, the reading time and the type, so a gateway that resends after a dropped connection does not record the reading twice.
A fleet-wide daily upload
curl -X POST "https://dppapi-production.up.railway.app/v1/passports/import-updates" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: fleet-north-2027-06-02" \-d '{"modelId": "cm1q8x2k40003l70f9a8s7d6e","rows": [{"uniqueIdentifier": "C-7KQ2M9XHT4R","readings": {"cycleCount": 812,"remainingCapacity": 14.1,"timeExtremeHighTemp": 42}},{"uniqueIdentifier": "C-4HZN8Q3RVX2","readings": {"cycleCount": 640,"remainingCapacity": 14.5}}]}'BMS resets
If a BMS software reset invalidates the history behind earlier state-of-health values, record it: send the next event with bmsHistoryInvalidatedByReset: true, or a BMS_SOFTWARE_RESET event. Readers of the passport then know earlier values cannot be compared with later ones (Art. 14).
Reading history back
curl "https://dppapi-production.up.railway.app/v1/passports/cm1q8y0bq0006l70fx9y8z7w6/events?event_type=SOH_READING&since=2027-01-01T00%3A00%3A00Z" \-H "Authorization: Bearer $DPP_API_KEY"