---
title: Set condition flags
description: Set or clear condition-classification flags on a passport. Approving a flag can make fields required and block publishing if those fields are empty.
canonical: "https://www.tracepass.eu/docs/set-condition-flags"
locale: en
source: "https://www.tracepass.eu/docs/set-condition-flags"
---

# Set condition flags

> Set or clear condition-classification flags on a passport. Approving a flag can make fields required and block publishing if those fields are empty.

```http
PATCH /api/v1/passports/{id}/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.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `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. |
| `id` | path | ObjectId | yes | Passport ID. |
| `Idempotency-Key` | header | string | no | 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. |

## Examples

```bash
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}'
```

```typescript
const res = await fetch(
  `https://app.tracepass.eu/api/v1/passports/${id}/condition-flags`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ hasBMS: true, rechargeable: true }),
  },
);
const { conditionProfile, version } = await res.json();
console.log("Updated profile:", conditionProfile, "version:", version);
```

```python
import os, uuid, requests
res = requests.patch(
    f"https://app.tracepass.eu/api/v1/passports/{passport_id}/condition-flags",
    headers={
        "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"hasBMS": True, "rechargeable": True},
)
res.raise_for_status()
data = res.json()
print("version:", data["version"])
for flag, info in data["conditionProfile"].items():
    print(flag, "→", info["value"], f"({info['status']})")
```

## Responses

### 200 — Flags updated

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

### 400 — Unknown flag key

```json
{
  "error": "Unknown condition flag keys",
  "details": "Keys not registered for category \"battery\": unknownFlag"
}
```

### 402 — Payment required

```json
{ "error": "Active subscription required" }
```

### 404 — Not found

```json
{ "error": "Passport not found" }
```

## Related

- [Get condition flags](https://www.tracepass.eu/docs/get-condition-flags.md)
- [Check passport compliance](https://www.tracepass.eu/docs/passport-compliance.md)