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

    ObjectId

    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