---
title: "Set or clear condition-classification flags on a passport."
method: PATCH
path: "/api/v1/passports/{id}/condition-flags"
tags: ["Passports"]
---

# Set or clear condition-classification flags on a passport.

`PATCH /api/v1/passports/{id}/condition-flags`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports/{id}/condition-flags`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.tracepass.eu/api/oauth/authorize`, token URL `https://app.tracepass.eu/api/oauth/token`, scopes: `passports:write`)

Write one or more condition flags. The body is
`Record<flagKey, boolean | null>` — `true`/`false` set the flag,
`null` clears it. Only keys registered for the passport's category
are accepted (unknown keys return 400).

**Warning:** approving a flag can make previously optional fields
required. If the passport is already published, enabling a flag
whose gate applies will raise a `conditional_missing` finding on the
next compliance check — fix those fields before or immediately after
setting the flag or the passport will be unrepublishable until they
are filled.

v1 writes default to `status: "approved"` (trusted integration).
Each flag change is audited with `"via API key <prefix>"` in the
flag's internal audit trail.

Supports `Idempotency-Key`. Counts as one v1 write.

## Request body

- ConditionFlagsPatch: Partial update for the condition profile. Each key must be registered for the passport's category (unknown keys return 400). Set a flag with `true`/`false`; clear it with `null`. Provide at least one key.

## Response `200`

Condition profile after the update.

- object
  - `passportId` string, required: MongoDB ObjectId hex string (24 chars).
  - `conditionProfile` ConditionProfile, required: A map of flagKey → ConditionFlag representing the resolved condition profile for a passport. Valid flag keys are category-specific: `battery` supports `hasBMS`, `rechargeable`, `externalStorageOnly`, and `isStationaryBess`. Categories with no flags return an empty object. The `audit` array is stripped from v1 responses.
  - `version` integer, required

## Other responses

- `400`: Validation error or malformed request.
- `401`: Missing or invalid API key.
- `402`: The subscription is past due, unpaid or canceled. Creating new content is blocked until billing is resolved; published passports stay accessible.
- `404`: Resource doesn't exist or is in a different workspace.
- `422`: Idempotency-Key reused with a different request body. Use a new key for the new request, or reuse the original body.
- `429`: Daily v1 write or passport-read budget exhausted. Resets at 00:00 UTC.

---

[API](https://skmtc.dev/tracepass/apis/tracepass-api.md) · [All operations](https://skmtc.dev/tracepass/apis/tracepass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracepass/apis/tracepass-api/revisions/60ddeb25638b?raw)