---
title: "Ler Cartão de Cidadão (frente+verso) e devolver campos para autofill do cliente"
method: POST
path: "/api/clients/ocr-document"
tags: ["Clients - Protected"]
---

# Ler Cartão de Cidadão (frente+verso) e devolver campos para autofill do cliente

`POST /api/clients/ocr-document`

OCR a Portuguese Cartão de Cidadão via Claude Vision and return the storable
client fields (nome, nif, nº documento, validade, entidade emissora) for the
create-client form to prefill. Data-minimized: no DOB/sex/filiação/NISS.

RGPD: this route reads the images in-memory and never persists them. When the
client is created, the frontend attaches them as Documentos do cliente (módulo
12, tipo CC) via POST /documents-test/ — same retention as a manual upload.
Unreadable/unsupported input returns success=False (never a 5xx); billing only
fires on success. Heavy sync work runs in the threadpool (same pattern as
/vehicles/ocr-document).

## Headers

- `x-api-token` string, nullable

## Response `200`

Successful Response

- CitizenCardOcrResult — Result of POST /api/clients/ocr-document (mirrors VehicleOcrResult): flat fields + success/error_message — an unreadable document is success=False, never a 500. Data-minimized: only fields with a Cliente column are returned (no DOB/sex/filiação/NISS). This endpoint processes the images in memory and never persists them; if the client is created, the frontend attaches them as Documentos do cliente (módulo 12, tipo CC) via POST /documents-test/ — same retention as a manual upload. No client created, nothing stored.
  - `success` boolean
  - `error_message` string, nullable
  - `billed` boolean
  - `doc_type` string, nullable
  - `confianca` string, nullable
  - `warnings` string[]
  - `nome` string, nullable
  - `nif` string, nullable
  - `numero_documento` string, nullable
  - `validade` string, nullable
  - `entidade_emissora` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/multigest/apis/multigest-protected-api.md) · [All operations](https://skmtc.dev/multigest/apis/multigest-protected-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/multigest/multigest-protected-api/revisions/4b44eb76b3ee/schema)