# OCR an identity document via vision LLM

Operation ID: `patient.assistantOcr`

Extract identity-document fields (name, DOB, address, etc.) from a photo using a vision-capable LLM. Separate from the Textract-based `patient.analyzeIdentityDocument` route. No authentication is required.

## Public method

`ocrIdentityDocument`

Signature: `patient.ocrIdentityDocument(request)`

Return type: `Promise<OcrResponse>`

## Authentication

Classification: **PUBLIC**

## Prerequisites

None documented.

## HTTP

`POST /assistant/ocr`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`AssistantOcrRequest`](../models/AssistantOcrRequest.md) | No |  |  |  | No |  |

Request model: [`AssistantOcrRequest`](../models/AssistantOcrRequest.md)

## Request example

```json
{
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`AssistantOcrResponse`](../models/AssistantOcrResponse.md) | application/json | Extracted identity-document fields |

## Success response examples

### 200

```json
{
  "fields": {
    "City": "Testville",
    "Country": "USA",
    "DOB": "01/01/1990",
    "ExpiresDate": "01/01/2030",
    "EyeColor": "Brown",
    "FirstName": "Test",
    "HairColor": "Black",
    "Height": "170 cm",
    "IDNumber": "ID-EXAMPLE-001",
    "IssuedDate": "01/01/2025",
    "LastName": "User",
    "Sex": "X",
    "State": "CA",
    "StreetAddress": "123 Example Street",
    "Weight": "70 kg",
    "ZipCode": "12345"
  },
  "ok": true,
  "type": "ocr_result"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | `object` | application/json | The image is missing, too large, not a valid data URI, or an unsupported MIME type |
| `422` | `object` | application/json | The LLM is not configured, the call failed, or the document was not legible |

## Error examples

### 400 — The image is not a valid base64 data URI

```json
{
  "error": "Image must be a base64 data URI (data:image/jpeg;base64,...). Received a string that is not a valid data URI.",
  "ok": false,
  "type": "ocr_error"
}
```

### 400 — No image provided

```json
{
  "error": "No image provided.",
  "ok": false,
  "type": "ocr_error"
}
```

### 422 — The document could not be read

```json
{
  "error": "Couldn't read the document. Check the image and try again.",
  "ok": false,
  "type": "ocr_error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { OcrRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
};

const result = await patient.ocrIdentityDocument(request);
```

## cURL

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="}' \
  'https://dev-api-patient.health.cloud/assistant/ocr'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.