---
title: "Update one field on a passport (by serial)."
method: PATCH
path: "/api/v1/passports/by-serial/{serial}/fields/{key}"
tags: ["Passports"]
---

# Update one field on a passport (by serial).

`PATCH /api/v1/passports/by-serial/{serial}/fields/{key}`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports/by-serial/{serial}/fields/{key}`
- 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`)

Same body, same response, and same semantics as PATCH
`/api/v1/passports/{id}/fields/{key}`.

## Request body

- UpdateFieldInput
  - `value` unknown, required
  - `source` 'manual' | 'ai_suggested' | 'reference_db' | 'supplier': Tag the origin of the value. Default `manual`. `ai_suggested` lands in the review queue; the others write with the caller's own rights (see the operation). A response may still show `ai_approved` or `system`: TracePass sets those, and a request claiming them is refused (400).
  - `sourceLocale` string: ISO 639-1 locale of the value. One of the 24 EU locales. Defaults to the passport's `sourceLocale`.

## Response `200`

Field updated.

- object
  - `field` PassportField, required
    - `value` unknown
    - `source` 'manual' | 'ai_suggested' | 'ai_approved' | 'reference_db' | 'supplier' | 'system' | 'derived': Who set the stored value. `derived` is a value calculated from other fields by a formula, not written by an AI model.
    - `aiProvenance` AiProvenance: Marks a value an AI system generated (EU AI Act Art. 50(2)). It stays on the field after a person approves or edits the value; only the two review flags change. Public passport outputs (viewer, JSON-LD, credential, PDF) mark the `research` and `translation` kinds.
      - `kind` 'research' | 'translation' | 'extraction': `research`: found and written by the AI. `translation`: machine translated. `extraction`: read from a document you uploaded.
      - `generatedAt` string, date-time
      - `model` string: The model that generated the value. Returned only to the owning account.
      - `humanReviewed` boolean
      - `humanEdited` boolean
    - `aiTranslated` boolean: Present and `true` on a `?lang=` response when the returned value is a machine translation (EU AI Act Art. 50(2) marking).
    - `sourceProvider` string: Identifier of the reference source that vouches for an AI-suggested value (for example a public register), with `sourceUrl` linking to its record where one is published. An open string: the set of sources can grow, so treat unknown values as "a named source". Absent when no single source vouches for the stored value, such as a value read from your own document or submitted by a supplier.
    - `sourceUrl` string, uri: The provider's canonical URL for this value, when it published one. Machine-readable companion to `evidence`.
    - `status` string
    - `accessLevel` string
    - `sourceLocale` string
    - `translations` object
    - `lastUpdatedAt` string, date-time
    - `lastUpdatedBy` string
  - `version` integer, required

## Other responses

- `400`: Validation error or malformed request.
- `401`: Missing or invalid API key.
- `404`: Resource doesn't exist or is in a different workspace.
- `409`: The serial maps to more than one passport in your account (serials are unique per GTIN, not per account). The request is rejected rather than acting on the wrong passport. Pass `?gtin=<gtin>` to disambiguate, or address the passport by its id instead. `count` is how many passports the serial matched.
- `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)