Global Data
Browse endpoints
View as Markdown OpenAPI spec

Extract ID Document Data & Face Image

POST /api/v2/id_extract operationId: id_extract

Live: https://gdapi.globaldata.net.au/api/v2/id_extract · Sandbox: 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

Content type application/json. ID document type and base64-encoded image(s) to extract.

FieldDescription
document_typerequired string

Type of document supplied.

Enum: passport, licence, medicare

Example: passport
document_photorequired string

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

Responses

200

Document successfully processed and data extracted.

application/json
FieldDescription
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

Extracted document data (structure depends on document_type).
Passport extraction result
FieldDescription
photo string

Base64 encoded cropped face image.

Example: iVBORw0KGgoAAAANSUhEUg...
face_occluded one of 2 shapes

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

first_name string

Example: JOHN MICHAEL
last_name string

Example: SMITH
birth_date string (date)

Example: 1990-01-01
expiry_date string (date)

Example: 2030-01-01
gender string

Example: M
passport_number string

Example: M1234567A
country string

Example: AUS
Driver licence extraction result
FieldDescription
photo string

Base64 encoded cropped face image.

Example: iVBORw0KGgoAAAANSUhEUg...
face_occluded one of 2 shapes

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

first_name string

Example: JOHN
middle_name string

Example: Michael
last_name string

Example: SMITH
birth_date string (date)

Example: 1990-01-01
address string

Example: 123 MAIN ST, SYDNEY NSW 2000
expiry_date string (date)

Example: 2030-01-01
conditions string

Example: AAA
licence_state string

Example: NSW
card_number string

Example: 123456789
Medicare card extraction result
FieldDescription
card_color string

Example: green
card_number string

Example: 1234567890
expiry_date string

Expiry date (YYYY-MM or YYYY-MM-DD, depending on what is detected).

Example: 2035-01
people array of objects

Card holders listed on the Medicare card.
people[].ref_number string

Example: 1
people[].name array of strings

Lines of the name as they appear on the card.
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous Global Data Check Next Create an ID Pass