# Extract ID Document Data & Face Image

`POST /id_extract`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/id_extract`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/id_extract`

Performs OCR / data extraction on an identity document image and (when available) returns parsed fields
plus a cropped face portrait (`photo`). Supported document types are:
* `passport`
* `licence` (Australian driver licence – requires front & back images)
* `medicare` (Australian Medicare card – front image only)

The response structure under `result` varies by `document_type` (see schema & examples below). All
successful responses include a base64-encoded face image when a face is detected (`photo`).

## Inputs

Supply images as base64 **data URI** strings (e.g. `data:image/jpeg;base64,/9j/4AA...`) or raw base64.
Only JPEG format is accepted for this endpoint. Maximum file size per image is 16 MB. For `licence`, both
front (`document_photo`) and back (`document_back`) images are required.

| Field | Required | Type | Notes |
|:------|:---------|:-----|:------|
| `document_type` | Yes | enum | One of `passport`, `licence`, `medicare` |
| `document_photo` | Yes | string | Base64 JPEG (front) |
| `document_back` | Conditionally | string | Base64 JPEG (back) – required when `document_type = licence` |
| `photo_border_percent` | No | integer | Border padding around the extracted face photo as a percentage of the detected face box (0-50, default 15) |

## Output (result object)

Depending on `document_type`, typical extracted fields include:
* Passport: `first_name`, `last_name`, `birth_date` (YYYY-MM-DD), `expiry_date` (YYYY-MM-DD), `gender`, `passport_number`, `country`, `photo`, `face_occluded`.
* Licence: `first_name`, `middle_name`, `last_name`, `birth_date`, `address`, `expiry_date` (YYYY-MM-DD), `conditions`, `licence_state`, `card_number`, `photo`, `face_occluded`.
* Medicare: `card_color`, `card_number`, `expiry_date` (YYYY-MM or YYYY-MM-DD), `people` (array of holders with `ref_number` & `name` lines).

Additional or fewer fields may appear depending on document quality and internal extraction logic.

## Error Handling

* Validation errors (missing / invalid fields, size limits, unsupported mime) return HTTP 400 with a descriptive `message`.
* Known processing errors from the document analysis engine (e.g. `no_face_found`) return HTTP 400 with that message.
* Unknown processing failures return HTTP 500 with `An error occurred while processing the document.`
* Entitlement / auth / rate limit errors use standard Global Data API response references.

## Auditing & Privacy

For compliance, sensitive fields and raw images are obfuscated in internal audit logs (masked with `X`). The
API response itself returns the actual extracted values so you should persist / redact them according to your
own data handling policies.

## Request body

ID document type and base64-encoded image(s) to extract.

| Field | Type | Description |
|-------|------|-------------|
| `document_type` | string | **Required.** Type of document supplied. Enum: `passport`, `licence`, `medicare` Example: `passport` |
| `document_photo` | string | **Required.** Base64 (optionally data URI) JPEG image of the front of the document. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `document_back` | string | Base64 (optionally data URI) JPEG image of the back of the document (licence only). Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `photo_border_percent` | integer [0..50] | Border padding added around the detected face box in the extracted face photo (`photo`), expressed as a percentage of the detected face box dimensions. Use a larger value to keep more spacing around the face in the cropped photo. Not applicable to `medicare`. Default: `15` Example: `25` |

**Sample request**

```json
{
    "document_type": "passport",
    "document_photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "photo_border_percent": 25
}
```

## Responses

### 200 Document successfully processed and data extracted.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` on success. Example: `Ok` |
| `api_reference` | string (uuid) | Unique audit reference for this request. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `result` | one of 3 shapes | One of: Passport extraction result; Driver licence extraction result; Medicare card extraction result. Extracted document data (structure depends on `document_type`). |
| `result (Passport extraction result).photo` | string | Base64 encoded cropped face image. Example: `iVBORw0KGgoAAAANSUhEUg...` |
| `result (Passport extraction result).face_occluded` | one of 2 shapes | One of: boolean; number. Whether face occlusion was detected for the cropped face image. Returns `false` when the face is not considered occluded. When the face has been considered occluded, this field returns a percentage confidence that the face is occluded. This is not an indication of the proportion of the face that is occluded. boolean: boolean, one of `false`, e.g. `false` number: number (float), e.g. `97.5` |
| `result (Passport extraction result).first_name` | string | Example: `JOHN MICHAEL` |
| `result (Passport extraction result).last_name` | string | Example: `SMITH` |
| `result (Passport extraction result).birth_date` | string (date) | Example: `1990-01-01` |
| `result (Passport extraction result).expiry_date` | string (date) | Example: `2030-01-01` |
| `result (Passport extraction result).gender` | string | Example: `M` |
| `result (Passport extraction result).passport_number` | string | Example: `M1234567A` |
| `result (Passport extraction result).country` | string | Example: `AUS` |
| `result (Driver licence extraction result).photo` | string | Base64 encoded cropped face image. Example: `iVBORw0KGgoAAAANSUhEUg...` |
| `result (Driver licence extraction result).face_occluded` | one of 2 shapes | One of: boolean; number. Whether face occlusion was detected for the cropped face image. Returns `false` when the face is not considered occluded. Returns a percentage confidence when face occlusion is detected. This value is the confidence that the face is occluded, not the proportion of the face that is covered. boolean: boolean, one of `false`, e.g. `false` number: number (float), e.g. `97.5` |
| `result (Driver licence extraction result).first_name` | string | Example: `JOHN` |
| `result (Driver licence extraction result).middle_name` | string | Example: `Michael` |
| `result (Driver licence extraction result).last_name` | string | Example: `SMITH` |
| `result (Driver licence extraction result).birth_date` | string (date) | Example: `1990-01-01` |
| `result (Driver licence extraction result).address` | string | Example: `123 MAIN ST, SYDNEY NSW 2000` |
| `result (Driver licence extraction result).expiry_date` | string (date) | Example: `2030-01-01` |
| `result (Driver licence extraction result).conditions` | string | Example: `AAA` |
| `result (Driver licence extraction result).licence_state` | string | Example: `NSW` |
| `result (Driver licence extraction result).card_number` | string | Example: `123456789` |
| `result (Medicare card extraction result).card_color` | string | Example: `green` |
| `result (Medicare card extraction result).card_number` | string | Example: `1234567890` |
| `result (Medicare card extraction result).expiry_date` | string | Expiry date (YYYY-MM or YYYY-MM-DD, depending on what is detected). Example: `2035-01` |
| `result (Medicare card extraction result).people` | array of objects | Card holders listed on the Medicare card. |
| `result (Medicare card extraction result).people[].ref_number` | string | Example: `1` |
| `result (Medicare card extraction result).people[].name` | array of strings | Lines of the name as they appear on the card. |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "result": {
        "photo": "iVBORw0KGgoAAAANSUhEUg...",
        "face_occluded": false,
        "first_name": "JOHN MICHAEL",
        "last_name": "SMITH",
        "birth_date": "1990-01-01",
        "expiry_date": "2030-01-01",
        "gender": "M",
        "passport_number": "M1234567A",
        "country": "AUS"
    }
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))