TracePass
Passports

Send a battery passport to an EN 18222 registry API

Sends a published **battery** passport to a registry that accepts the EN 18222 `registerDPP` call, using the registry API access your account has configured (an API key or a bearer token), so the entry is made under your own credentials. Battery passports only.

POST/api/v1/passports/{id}/place-on-market
Download OpenAPI 3.1
POST/api/v1/passports/{id}/place-on-market

Send a battery passport to an EN 18222 registry API

Sends a published **battery** passport to a registry that accepts the EN 18222 `registerDPP` call, using the registry API access your account has configured (an API key or a bearer token), so the entry is made under your own credentials. Battery passports only.

**This is not the way into the EU DPP Registry.** The Commission's Registry does not accept this call or these credentials: the economic operator registers there on the Registry website, under its own EU Login. For that path, get the address to paste into the Registry's form (`POST /api/v1/passports/{id}/registry-upi`) or an upload file (`POST /api/v1/registry/upload-file`), then record the Registry's answer (`POST /api/v1/passports/{id}/registration`).

**Paid plans only** (`402` on Free): a Free passport expires after 30 days, and a registered passport that stops resolving breaks the registration.

**Asynchronous.** The call checks the passport, sets `placeOnMarketStatus` to `placing` and answers `202` with `{ passport, passportId, status: "placing", dppId }`. The registry call follows in the background, with automatic retries while the registry is unreachable. Read the passport to follow it: `placed` means the registry accepted it (`placedOnMarketAt`, and `registrationId` when the registry returned one) and fires the `passport.placed_on_market` webhook; `rejected` means the registry refused it or could not be reached once the retries ran out (`registrationRejectedAt`, `registrationRejectionReason`) and fires `passport.placement_rejected`. To retry, fix the cause and call this endpoint again — a rejected passport may be placed again, and the new attempt clears the old rejection. If the passport has no DPP ID yet, one is assigned and returned as `dppId`.

Refusals answer **409** with a code, checked in this order: `not_a_battery`, `not_published` (only a published passport can be placed), `already_placed` (placing or placed), `operator_id_missing` (the account has no economic-operator identifier; set it in the company settings), `registry_not_configured` (no registry API access is configured for the account; an admin sets it in the dashboard under Settings → EN 18222 registry API), `registry_host_not_allowed` (TracePass does not send registrations to the registry address configured for the account; check the registry URL under Settings → EN 18222 registry API) and `registry_not_ready`, whose `findings[]` lists the registry-readiness findings that stand in the way (`findingDetails[]` carries the same findings with their severity, blocking ones first) — the registry-readiness check returns them in structured form.

**After placement the operator is locked:** a party write that would change a stored `operatorIdentifier` or `facilityIdentifier` answers 409 `operator_locked`. To correct one, mark the passport for deletion and create a new one. No request body. Counts as one v1 write, and only when the call is accepted. Honours `Idempotency-Key`.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID of a published battery passport.

Headers

  • Authorizationrequired

    string

    `Bearer <token>` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4.

Request

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/place-on-market \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 3f1c9a52-8b7e-4d6a-9f0e-2c4b6d8e0a13"

Response

{
  "passport": {
    "_id": "6650b2c3d4e5f6a7b8c9d0e1",
    "status": "published",
    "placeOnMarketStatus": "placing"
  },
  "passportId": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "placing",
  "dppId": "https://id.tracepass.eu/dpp/7b1e4c2a-5f3d-4e8a-9c6b-2d1f0a3e5b7c"
}