TracePass
Get started
Passports

Set condition flags

Write one or more condition flags to a passport. The request body is Record<flagKey, boolean | null> — true or false sets the flag; null clears it. Only keys registered for the passport's category are accepted; unknown keys return 400 with a list of valid keys for that category.

PATCH/api/v1/passports/{id}/condition-flags
Download OpenAPI 3.1
PATCH/api/v1/passports/{id}/condition-flags

Set condition flags

Write one or more condition flags to a passport. The request body is Record<flagKey, boolean | null> — true or false sets the flag; null clears it. Only keys registered for the passport's category are accepted; unknown keys return 400 with a list of valid keys for that category.

Warning: approving a flag can make previously optional fields required. For battery passports, hasBMS: true gates the BMS-related Annex XIII 4(b) fields; rechargeable: true activates the charge-cycle and state-of-health fields under Art. 10(1); isStationaryBess: true activates the Annex VII Part A and B fields. If the passport is already published and those fields are empty, the next compliance check will raise conditional_missing critical findings — fix those fields before or immediately after setting the flag or the passport will fail republication.

v1 writes default to status: "approved" (trusted integration). Each flag change is written to the flag's internal audit trail with "via API key <prefix>". The full audit trail is visible in the dashboard but stripped from this response. Supports Idempotency-Key. An alternate addressing form exists at PATCH /api/v1/passports/by-serial/{serial}/condition-flags with the same body and response shapes. Counts as one v1 write against the daily cap.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID.

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

    Optional idempotency key (UUID v4 or any opaque string ≤ 64 chars). Same key + same body replays the cached response for 24 h; same key + different body returns 422.

Request

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/condition-flags \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"hasBMS": true, "rechargeable": true}'

Response

{
  "passportId": "6650b2c3d4e5f6a7b8c9d0e1",
  "conditionProfile": {
    "hasBMS": {
      "value": true,
      "status": "approved",
      "source": "api:tp_abc123"
    },
    "rechargeable": {
      "value": true,
      "status": "approved",
      "source": "api:tp_abc123"
    }
  },
  "version": 4
}

Related endpoints