# OCR an insurance card via vision LLM

Operation ID: `patient.assistantOcrInsurance`

Extract insurance-card fields (member id, group number, plan, RxBIN/PCN/GRP, etc.) from a photo of the card's front using a vision-capable LLM. Mirrors the request/error shape of `patient.assistantOcr`. No authentication is required.

## Public method

`ocrInsuranceDocument`

Signature: `patient.ocrInsuranceDocument(request)`

Return type: `Promise<OcrResponse>`

## Authentication

Classification: **PUBLIC**

## Prerequisites

None documented.

## HTTP

`POST /assistant/ocr-insurance`

## Path parameters

None.

## Query parameters

None.

## Body parameters

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

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

## Request example

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

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`AssistantOcrInsuranceResponse`](../models/AssistantOcrInsuranceResponse.md) | application/json | Extracted insurance-card fields |

## Success response examples

### 200

```json
{
  "fields": {
    "EffectiveDate": "01/01/2025",
    "FirstName": "Test",
    "GroupNumber": "GRP-example-001",
    "InsurerName": "Example Health Plan",
    "LastName": "User",
    "MemberID": "MEM-example-001",
    "PlanName": "Example Health Plan",
    "RxBIN": "000000",
    "RxGRP": "RX-EXAMPLE",
    "RxPCN": "EXAMPLE"
  },
  "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 card 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 card 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.ocrInsuranceDocument(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-insurance'
```

## 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.