# Read an ID Pass

`POST /idpass/details`

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

Read the details from an ID Pass

Please review the full ID Pass documentation here:

[ID Pass documentation](/docs/guides/idpass)

## Data encryption

All data stored for the ID Pass is encrypted at rest to ensure the security and privacy of sensitive
information. Additionally, particularly sensitive fields are encrypted using a unique cipher key that is
generated for each ID Pass.

The cipher key is securely included in the ID Pass register response and is deleted from our systems once
the ID Pass is completed by the end user.

This design ensures that we have no capability to decrypt the data once the cipher key has been deleted.

 ### Important notes on encryption

- **Irretrievability of Data:**
If the cipher key is lost, there is no way to recover or decrypt the associated ID Pass data. It is you
responsibility to securely store and manage the cipher key.

- **Compliance:**
This encryption approach ensures compliance with privacy regulations by minimizing exposure of sensitive data.

- **Decryption:**
To access sensitive fields (e.g., validation results, documents, or images), you must supply the cipher key
when retrieving the ID Pass data. Without the cipher key, encrypted data will be returned for local decryption.

## Recalling Encrypted Data

You can include the cipher key (returned during ID Pass creation) in your request to handle encrypted data
as follows:

- **With Cipher Key:**
If the cipher key is provided, sensitive fields will be decrypted and returned in plain text.

- **Without Cipher Key:**
If no cipher key is supplied, the encrypted data will be returned for local decryption using the provided
cipher key.

- **Compliance Considerations**
Ensure your decision to include the cipher key aligns with your compliance and security policies.

### Fields Encrypted
- **Validation Results:** Field: validation_summary
- **Requested Identity:** Field: config.requested_identity
- **Document Details:** Field: documents
- **Captured Images:** Field: images

## Encryption and Decryption:
The data is encrypted using the AES-256-CBC cipher. Use the following pseudocode to decrypt the data locally:

### Decrypting Data
```
function decryptData(encryptedData, cipherKey, iv):
  // Decode the cipher key and initialization vector (IV)
  decodedKey = base64Decode(cipherKey)
  decodedIV = base64Decode(iv)

  // Decrypt the data using AES-256-CBC
  decryptedData = AES256_CBC_Decrypt(encryptedData, decodedKey, decodedIV)

  return decryptedData
```

### Validating Integrity with MAC
```
function validateMAC(data, iv, cipherKey):
  // Concatenate the IV and encrypted data
  combinedData = iv + data

  // Generate a MAC using HMAC-SHA256
  mac = HMAC_SHA256(combinedData, base64Decode(cipherKey))

  return mac
```

## Request body

The details of the ID Pass to retrieve

| Field | Type | Description |
|-------|------|-------------|
| `id` | string (uuid) | The id of the ID Pass to retrieve Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `cipher_key` | string or null | The cipher_key for this ID Pass. If the cipher_key is provided then the response will be read from the system and decrypted before returning. Alternatively, if no cipher_key is supplied, then the encrypted data will be returned and can be decrypted locally. Example: `IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA=` |
| `return_logs` | boolean or null | Optionally return the debug log from the ID Pass. The log contains information about each step which was attempted by the user and can be useful to help understand user issues. Logs are returned in the logs response parameter. Example: `true` |
| `return_images` | boolean or null | Optionally return the images captured during the ID Pass process. This will include the probe image extracted from the liveness face verification (if requested) and the front / back and photo images from the documents which were validated as well as the optional ID photo image. Note that images are only stored for the period in the image_retention_days parameter from the ID Pass creation. If image retention days is set to 0 then the images will be deleted once the ID Pass is complete and this endpoint will never return image data for the ID Pass, even while it is still in progress. Once the retention period has passed and the images have been deleted, the images response parameter is no longer included. Images are returned in the images response parameter. Example: `true` |
| `return_documents` | boolean or null | Optionally return detailed information about each of the documents which was assessed during the ID Pass process. This includes the full OCR information captured as well as the information which was validated. Example: `true` |

**Sample request**

```json
{
    "id": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "cipher_key": "IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA=",
    "return_logs": true,
    "return_images": true,
    "return_documents": true
}
```

## Responses

### 200 Details of the ID Pass

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request for support queries. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `id` | string (uuid) | The identifier for this ID Pass. |
| `link` | string (url) | The ID Pass link to be provided to your user Example: `https://idpass.globaldata.net.au/idpass?token=abcd123456` |
| `status` | string | The status of the ID Pass * `new` - The ID Pass has not yet been used * `opened` - The USer has proceeded past the welcome page * `in_progress` - The user has given consent to proceed * `complete` - The ID Pass has been completed * `expired` - The ID Pass has expired (reached link_validity_days) * `failed` - The ID Pass has failed * `cancelled` - The ID Pass has been cancelled Enum: `new`, `opened`, `in_progress`, `complete`, `expired`, `failed`, `cancelled` Example: `new` |
| `verification_status` | string | The verification status of the ID Pass: * `passed` - The user passed the ID Pass process * `failed` - The ID failed to verify * `null` - The ID Pass is in progress Enum: `passed`, `failed` Example: `passed` |
| `verification_description` | string | Human readable reason for the verification_status result Example: `Document 1 had biographic identity edits before verification The identity was verified successfully` |
| `config` | object | The original configuration parameters used to create the ID Pass. See the ID Pass Register definition for these values. |
| `config.link_validity_days` | integer | Number of days for which the link should remain available. Example: `3` |
| `config.image_retention_days` | integer | Number of days for which the images from the check will be stored. Example: `5` |
| `config.check_liveness` | boolean | Whether a face liveness check should be performed. Example: `true` |
| `config.document_1_allowed_types` | array of strings | The types of documents which are allowed for the first document check. |
| `config.document_2_allowed_types` | array of strings | The types of documents which are allowed for the second document check. |
| `config.document_3_allowed_types` | array of strings | The types of documents which are allowed for the third document check. |
| `config.webhook_url` | string | Webhook URL which the ID PAss system will call to notify events Example: `https://example.com/webhook` |
| `config.webhook_events` | array of strings | The events for which the webhook should be called |
| `config.return_url` | string | Optional URL to link to from the ID Pass complete page. Example: `https://example.com/return` |
| `config.privacy_policy_url` | string | The privacy policy URL which will be displayed on the consent page. This is taken from your account configuration. Contact support to make any changes to this link. Example: `https://example.com/privacy` |
| `config.requester_name` | string | Your company name as displayed on the consent page. This is taken from your account configuration. Contact support to make any changes to this field. Example: `Sample Company` |
| `config.requested_identity` | one of 2 shapes | One of: Decrypted identity; Encrypted identity. The customer identity details supplied at registration. When a cipher_key is provided this object is decrypted; otherwise the encrypted payload is returned for local decryption. |
| `config.requested_identity (Decrypted identity).first_name` | string | The first name of the person to be verified Example: `John` |
| `config.requested_identity (Decrypted identity).middle_name` | string | The middle name of the person to be verified Example: `Andrew` |
| `config.requested_identity (Decrypted identity).last_name` | string | The last name of the person to be verified Example: `Smith` |
| `config.requested_identity (Decrypted identity).date_of_birth` | string (date) | The date of birth of the person to be verified Example: `1990-03-21` |
| `config.requested_identity (Encrypted identity).iv` | string | The initialisation vector for decrypting the requested identity |
| `config.requested_identity (Encrypted identity).mac` | string | The message authentication code for the encrypted identity payload |
| `config.requested_identity (Encrypted identity).data` | string | The encrypted requested identity data |
| `created_at` | string | The date/time when the ID Pass was created Example: `2024-05-16T01:26:08+00:00` |
| `consent_given_at` | string | The date/time when the user checked the consent box Example: `2024-05-16T01:35:11+00:00` |
| `consent_text` | string | The text of the consent which was displayed to the user Example: `I confirm that I am authorised to provide my personal details...` |
| `completed_at` | string | The date/time when the user completed the ID Pass process Example: `2024-05-16T01:38:28+00:00` |
| `ip_address` | string | The IP address used to complete the ID Pass Example: `203.22.251.3` |
| `logs` | array of strings | Array of log messages returned when the return_logs option is set |
| `validation_summary` | one of 3 shapes | One of: Decrypted validation summary; Encrypted validation summary; Empty array. This includes the result for each document passed to validation and the identity which was verified. When a cipher_key is provided this object is decrypted; otherwise the encrypted payload is returned for local decryption. Returns an empty array if the validation summary has no data. The `date_of_birth` completion described below applies to the decrypted object only. Where no `cipher_key` was supplied the encrypted payload is returned exactly as stored, so decrypting it yourself gives a partial date in its stored `1980-03-00` / `1980-00-00` form and no `partial_date_of_birth` key. Empty array: Returned in place of an empty object for backward compatibility. When the associated object has no data, the API returns an empty array `[]` instead of an empty object `{}`. Clients should treat `[]` as equivalent to `{}` for these fields. This shape exists for backward compatibility and will not be removed. (array [max 0 items]) |
| `validation_summary (Decrypted validation summary).document_verification` | string | The document verification strategy that was used for this ID Pass. Mirrors the `config.document_verification` value. Enum: `dvs`, `idsp`, `basic` Example: `dvs` |
| `validation_summary (Decrypted validation summary).liveness_result` | object | The result of the liveness check. Only present when `check_liveness` is true. |
| `validation_summary (Decrypted validation summary).liveness_result.validated` | boolean | Whether the liveness check was successful Example: `true` |
| `validation_summary (Decrypted validation summary).liveness_result.confidence` | string | The confidence score for the liveness check, formatted as a string to three decimal places Example: `99.811` |
| `validation_summary (Decrypted validation summary).liveness_result.liveness_attempts` | integer | The number of liveness attempts Example: `1` |
| `validation_summary (Decrypted validation summary).liveness_result.bounding_box` | object | The bounding box of the liveness check |
| `validation_summary (Decrypted validation summary).liveness_result.bounding_box.top` | number | The top coordinate of the bounding box (percentage of image height) Example: `0.1` |
| `validation_summary (Decrypted validation summary).liveness_result.bounding_box.left` | number | The left coordinate of the bounding box (percentage of image width) Example: `0.1` |
| `validation_summary (Decrypted validation summary).liveness_result.bounding_box.width` | number | The width of the bounding box (percentage of image width) Example: `0.1` |
| `validation_summary (Decrypted validation summary).liveness_result.bounding_box.height` | number | The height of the bounding box (percentage of image height) Example: `0.1` |
| `validation_summary (Decrypted validation summary).id_photo_result` | object | The result of the ID photo check |
| `validation_summary (Decrypted validation summary).id_photo_result.status` | string | The status of the ID photo check Enum: `complete`, `failed`, `running` Example: `complete` |
| `validation_summary (Decrypted validation summary).id_photo_result.bounding_box` | object | The bounding box of the ID photo |
| `validation_summary (Decrypted validation summary).id_photo_result.bounding_box.top` | number | The top coordinate of the bounding box (percentage of image height) Example: `0.1` |
| `validation_summary (Decrypted validation summary).id_photo_result.bounding_box.left` | number | The left coordinate of the bounding box (percentage of image width) Example: `0.1` |
| `validation_summary (Decrypted validation summary).id_photo_result.bounding_box.width` | number | The width of the bounding box (percentage of image width) Example: `0.1` |
| `validation_summary (Decrypted validation summary).id_photo_result.bounding_box.height` | number | The height of the bounding box (percentage of image height) Example: `0.1` |
| `validation_summary (Decrypted validation summary).id_photo_result.image_passed` | boolean | Whether the ID photo passed the image check Example: `true` |
| `validation_summary (Decrypted validation summary).id_photo_result.biometric_passed` | boolean | Whether the ID photo passed the biometric check Example: `true` |
| `validation_summary (Decrypted validation summary).document_1_result` | object | The validation result for for document 1 |
| `validation_summary (Decrypted validation summary).document_1_result.document_type` | string | The document type Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` Example: `licence` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields` | object | The name and DOB fields from the document which were used in the validation. The exact set of fields depends on the document type. |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.first_name` | string | The first name on the document (licence, passport, visa, birth certificate) Example: `John` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.middle_name` | string or null | The middle name on the document (passport, visa) Example: `Andrew` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.last_name` | string | The last name on the document (licence, passport, visa, birth certificate) Example: `Smith` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.date_of_birth` | string (date) | The date of birth, always a whole date in `YYYY-MM-DD` form. Some Northern Territory birth certificates are issued with only a partial date of birth. In this circumstance, the `date_of_birth` field is completed by setting each unknown component to the first, and the `partial_date_of_birth` field is returned beside it carrying what was actually known. For example, if only March 1980 was known, the `date_of_birth` will be `1980-03-01` and the `partial_date_of_birth` will be `1980-03`. If only 1980 was known, the `date_of_birth` will be `1980-01-01` and the `partial_date_of_birth` will be `1980`. **A completed date is not a known date of birth if partial_date_of_birth is present.** Where `partial_date_of_birth` is absent, and it usually is, this is the whole date of birth as it appears on the document. Example: `1990-03-21` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.partial_date_of_birth` | string | What was actually known of the date of birth, when it was not the whole date: `YYYY` where only the year was known, `YYYY-MM` where the month and year were. It is this value the registry checked - the components missing from it were never sent. **This key is absent unless the date of birth is partial.** It is not returned as null or as an empty string; it simply does not appear. Today it appears only for some Northern Territory birth certificates. Example: `1980-03` |
| `validation_summary (Decrypted validation summary).document_1_result.validated_fields.full_name` | string | The full name on the document (medicare, centrelink) Example: `John Smith` |
| `validation_summary (Decrypted validation summary).document_1_result.biographic_validated` | boolean | Was the biographic information validated successfully? Example: `true` |
| `validation_summary (Decrypted validation summary).document_1_result.biometric_validated` | boolean | Was the biometric information validated successfully? (only available if a liveness check was performed) Example: `true` |
| `validation_summary (Decrypted validation summary).document_1_result.biometric_similarity` | string or null | The biometric similarity score between the document photo and the liveness probe image, formatted as a string to three decimal places. Null if not available. Example: `99.804` |
| `validation_summary (Decrypted validation summary).document_1_result.biometric_threshold` | integer or null | The threshold which the biometric similarity was compared against. Null if not available. Example: `80` |
| `validation_summary (Decrypted validation summary).document_1_result.changes` | one of 2 shapes | One of: Changes made by the user; Empty array. Object containing any changes the user made to the OCR-extracted information before validation. Each key is the name of a changed field, and the value is a `from`/`to` pair where `from` is the original OCR value and `to` is the value as changed by the user. Empty array when no changes were made. Changes made by the user: object (dynamic) Empty array: Returned in place of an empty object for backward compatibility. When the associated object has no data, the API returns an empty array `[]` instead of an empty object `{}`. Clients should treat `[]` as equivalent to `{}` for these fields. This shape exists for backward compatibility and will not be removed. (array [max 0 items]) |
| `validation_summary (Decrypted validation summary).document_2_result` | object | The validation result for for document 2 (see document_1_result for details) |
| `validation_summary (Decrypted validation summary).document_3_result` | object | The validation result for for document 3 (see document_1_result for details) |
| `validation_summary (Decrypted validation summary).verified_identity` | object or null | The Identity which was verified. Null when no consistent identity could be established across documents. |
| `validation_summary (Decrypted validation summary).verified_identity.first_name` | string | Example: `John` |
| `validation_summary (Decrypted validation summary).verified_identity.middle_name` | string or null | Example: `Andrew` |
| `validation_summary (Decrypted validation summary).verified_identity.last_name` | string | Example: `Smith` |
| `validation_summary (Decrypted validation summary).verified_identity.date_of_birth` | string (date) | The date of birth, always a whole date in `YYYY-MM-DD` form. Some Northern Territory birth certificates are issued with only a partial date of birth. In this circumstance, the `date_of_birth` field is completed by setting each unknown component to the first, and the `partial_date_of_birth` field is returned beside it carrying what was actually known. For example, if only March 1980 was known, the `date_of_birth` will be `1980-03-01` and the `partial_date_of_birth` will be `1980-03`. If only 1980 was known, the `date_of_birth` will be `1980-01-01` and the `partial_date_of_birth` will be `1980`. **A completed date is not a known date of birth if partial_date_of_birth is present.** Where `partial_date_of_birth` is absent, and it usually is, this is the whole date of birth as it appears on the document. Example: `1990-03-21` |
| `validation_summary (Decrypted validation summary).verified_identity.partial_date_of_birth` | string | What was actually known of the date of birth, when it was not the whole date: `YYYY` where only the year was known, `YYYY-MM` where the month and year were. It is this value the registry checked - the components missing from it were never sent. **This key is absent unless the date of birth is partial.** It is not returned as null or as an empty string; it simply does not appear. Today it appears only for some Northern Territory birth certificates. Example: `1980-03` |
| `validation_summary (Decrypted validation summary).requested_identity_mismatch` | boolean | True when a `requested_identity` was supplied on the ID Pass and the identity which was verified from the documents did not match it. This flag is purely informational - it does not itself fail the verification. Example: `false` |
| `validation_summary (Encrypted validation summary).iv` | string | The initialisation vector for decrypting the validation summary |
| `validation_summary (Encrypted validation summary).mac` | string | The message authentication code for the encrypted validation summary payload |
| `validation_summary (Encrypted validation summary).data` | string | The encrypted validation summary data |
| `documents` | one of 2 shapes | One of: Decrypted documents; Empty array. Full details of the documents which were validated. This field is only returned when `return_documents: true` is set on the details request. Returns an empty array if the documents object has no data. Empty array: Returned in place of an empty object for backward compatibility. When the associated object has no data, the API returns an empty array `[]` instead of an empty object `{}`. Clients should treat `[]` as equivalent to `{}` for these fields. This shape exists for backward compatibility and will not be removed. (array [max 0 items]) |
| `documents (Decrypted documents).document_1` | object | Details from the first document |
| `documents (Decrypted documents).document_1.document_type` | string | The document type Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` Example: `licence` |
| `documents (Decrypted documents).document_1.document_number` | integer | The document number. (1 for the first document) Example: `1` |
| `documents (Decrypted documents).document_1.ocr_status` | string or null | The OCR status of this document. For manual-entry document types (centrelink, birth_certificate), this is null. Enum: `running`, `failed`, `complete` Example: `complete` |
| `documents (Decrypted documents).document_1.ocr_attempts` | integer | The number of OCR attempts Example: `1` |
| `documents (Decrypted documents).document_1.validation_status` | string or null | The validation status of the document Enum: `running`, `failed`, `complete` Example: `complete` |
| `documents (Decrypted documents).document_1.validation_result` | one of 3 shapes | One of: DVS validation result; Basic validation result; IDSP validation result. The validation result for this document. The shape of this object depends on the `document_verification` strategy configured for the ID Pass (see config.document_verification). |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).strategy` | string | The verification strategy used Enum: `dvs` Example: `dvs` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).verification_result_code` | string or null | DVS result code * `Y` - The document is valid * `N` - The document is not valid * `D` - The document details could not be found For `nz_licence` documents `D` is never returned: the result is `Y` or `N`, and a source outage leaves the code null so the customer may retry. Enum: `Y`, `N`, `D` Example: `Y` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).verification_request_number` | string or null | The verification request number. This is needed for any official queries on the result. Example: `7a3ed6e1-b707-4e2d-bacb-e2dfe8f57406` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).additional_information` | array of objects or null | Additional details to support the result. For `nz_licence` documents there is one code: `NZDL-101` with the message "Document does not match". It is present only on an `N` result. |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).additional_information[].code` | string | The DVS code for the information. Example: `DL-006` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).additional_information[].message` | string | A human-readable message describing the additional information. Example: `Card number not matched.` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).originating_agency_code` | string or null | The originating agency code from DVS. Null for `nz_licence` documents. Example: `DVS123` |
| `documents (Decrypted documents).document_1.validation_result (DVS validation result).checked_at` | string or null | The date/time the validation was performed Example: `2026-04-16 04:28:53` |
| `documents (Decrypted documents).document_1.validation_result (Basic validation result).strategy` | string | The verification strategy used Enum: `basic` Example: `basic` |
| `documents (Decrypted documents).document_1.validation_result (Basic validation result).basic_validation_passed` | boolean | Whether the basic format validation passed Example: `true` |
| `documents (Decrypted documents).document_1.validation_result (Basic validation result).errors` | object (dynamic) | Per-field validation errors. Each key is a field name and the value is an array of error messages for that field. Empty object when validation passed. |
| `documents (Decrypted documents).document_1.validation_result (Basic validation result).checked_at` | string or null | The date/time the validation was performed Example: `2026-04-16 04:28:53` |
| `documents (Decrypted documents).document_1.validation_result (IDSP validation result).strategy` | string | The verification strategy used Enum: `idsp` Example: `idsp` |
| `documents (Decrypted documents).document_1.validation_result (IDSP validation result).verification_passed` | boolean | Whether the document verification passed (Global Data's identity opinion for this document) Example: `true` |
| `documents (Decrypted documents).document_1.validation_result (IDSP validation result).checked_at` | string or null | The date/time the validation was performed Example: `2026-04-16 04:28:53` |
| `documents (Decrypted documents).document_1.validation_attempts` | integer | Number of validation attempts for this document Example: `1` |
| `documents (Decrypted documents).document_1.biometric_result` | object | The result of the biometric face match comparison for this document. Only present when a liveness check was performed and the document has a photo. |
| `documents (Decrypted documents).document_1.biometric_result.passed` | boolean | If the biometric similarity is sufficient to pass the biometric pass threshold Example: `true` |
| `documents (Decrypted documents).document_1.biometric_result.threshold` | number | The biometric pass threshold percentage Example: `80` |
| `documents (Decrypted documents).document_1.biometric_result.similarity` | number | Similarity percentage between the probe image from the liveness check and the photo image on the document. Example: `98.8764` |
| `documents (Decrypted documents).document_1.biometric_result.face_occluded` | boolean | Whether the face on the document photo was detected as occluded (e.g. obscured by glasses, hair, or a covering). Example: `false` |
| `documents (Decrypted documents).document_1.ocr_data` | one of 3 shapes | One of: Decrypted OCR data; Encrypted OCR data; Empty array. Object of all fields returned from the OCR engine for this document. Fields differ for document types. See text for detailed descriptions. When a cipher_key is provided this object is decrypted; otherwise the encrypted payload is returned for local decryption. Returns an empty array if the documents object has no data. Empty array: Returned in place of an empty object for backward compatibility. When the associated object has no data, the API returns an empty array `[]` instead of an empty object `{}`. Clients should treat `[]` as equivalent to `{}` for these fields. This shape exists for backward compatibility and will not be removed. (array [max 0 items]) |
| `documents (Decrypted documents).document_1.ocr_data (Decrypted OCR data).first_name` | string | The first name on the document (actual fields will differ for each document type) Example: `example value` |
| `documents (Decrypted documents).document_1.ocr_data (Decrypted OCR data).last_name` | string | The last name on the document (actual fields will differ for each document type) Example: `example value` |
| `documents (Decrypted documents).document_1.ocr_data (Decrypted OCR data).date_of_birth` | string (date) | The date of birth on the document (actual fields will differ for each document type) Example: `1990-03-21` |
| `documents (Decrypted documents).document_1.ocr_data (Encrypted OCR data).iv` | string | The initialisation vector for decrypting the OCR data |
| `documents (Decrypted documents).document_1.ocr_data (Encrypted OCR data).mac` | string | The message authentication code for the encrypted OCR data payload |
| `documents (Decrypted documents).document_1.ocr_data (Encrypted OCR data).data` | string | The encrypted OCR data |
| `documents (Decrypted documents).document_1.validation_data` | one of 2 shapes | One of: Decrypted validation data; Encrypted validation data. Object of all fields sent for validation. Note that the content of these fields may differ from the ocr_data fields because the user may have made edits to the OCR data before validation. When a cipher_key is provided this object is decrypted; otherwise the encrypted payload is returned for local decryption. Fields are the values sent to the issuer for the check, with one exception: `date_of_birth` is completed to a whole date where the check was made on a partial one, and `partial_date_of_birth` beside it says what was actually sent. See those two fields. Birth certificates additionally carry `registration_number_as_entered`, which is what the person typed on the form. For some states the two differ, because the number printed on a birth certificate has to be transcribed into the form the DVS expects - a Western Australian certificate printed as `1/234/56X` is sent as `0100234`. `registration_number` is always the value that was sent. Where that transcription needed the person to supply the district, `district_number_confirmed` records the district they selected or confirmed - the evidence of how the sent number was arrived at, rather than only what was typed. See that field. This applies to the decrypted object only. Where no `cipher_key` was supplied the encrypted payload is returned exactly as stored, so decrypting it yourself gives the partial date in its stored `1980-03-00` / `1980-00-00` form and no `partial_date_of_birth` key. |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).first_name` | string | The first name on the document (actual fields will differ for each document type) Example: `example value` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).last_name` | string | The last name on the document (actual fields will differ for each document type) Example: `example value` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).date_of_birth` | string (date) | The date of birth on the document, always a whole date in `YYYY-MM-DD` form (actual fields will differ for each document type). Some Northern Territory birth certificates are issued with only a partial date of birth. In this circumstance, the `date_of_birth` field is completed by setting each unknown component to the first, and the `partial_date_of_birth` field is returned beside it carrying what was actually known. For example, if only March 1980 was known, the `date_of_birth` will be `1980-03-01` and the `partial_date_of_birth` will be `1980-03`. If only 1980 was known, the `date_of_birth` will be `1980-01-01` and the `partial_date_of_birth` will be `1980`. **A completed date is not a known date of birth if partial_date_of_birth is present.** Where `partial_date_of_birth` is absent, and it usually is, this is the whole date of birth as it appears on the document. Example: `1990-03-21` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).partial_date_of_birth` | string | What was actually known of the date of birth, when it was not the whole date: `YYYY` where only the year was known, `YYYY-MM` where the month and year were. It is this value the registry checked - the components missing from it were never sent. **This key is absent unless the date of birth is partial.** It is not returned as null or as an empty string; it simply does not appear. Today it appears only for some Northern Territory birth certificates. Example: `1980-03` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).registration_number` | string or null | Birth certificates only; the actual fields will differ for each document type. The registration number **sent to the registry** for the check. Where the printed number needs transcribing this is the transcribed value, not what was typed. Example: `0100234` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).registration_number_as_entered` | string or null | Birth certificates only; the actual fields will differ for each document type. The registration number **as the person typed it** on the form, exactly as printed on their certificate. Recorded so the entry can be shown back to them if the check fails, and so the value sent can be traced to what was entered. Null for Queensland and Tasmania, which are identified by registration date rather than number. Example: `1/234/56X` |
| `documents (Decrypted documents).document_1.validation_data (Decrypted validation data).district_number_confirmed` | string | Western Australian birth certificates only. The two-digit district number the person **selected or confirmed** on the form, which is the leading pair of digits of the `registration_number` that was sent. Older Western Australian certificates print a number like `1/234/56X` that carries no usable district, or one the registry warns is not always the district the birth was registered in. Where that happens the person is shown the district we read from the number and asked to confirm it, or to choose the right one. This field is the record of that answer, so the number that was sent can be traced to how it was arrived at rather than only to what was typed. `99` is not a separate district. It is Perth under an alternate district number used by some certificates issued between 1961 and 1983, which the person identifies by the table on their certificate having only four rows; where they say so, this field carries `99` in place of Perth's usual `01`. **This key is absent unless a district was selected or confirmed.** It is not returned as null or as an empty string; it simply does not appear. It is absent for every state other than Western Australia, and absent for a Western Australian certificate whose printed number resolves on its own, because nothing was asked. Example: `01` |
| `documents (Decrypted documents).document_1.validation_data (Encrypted validation data).iv` | string | The initialisation vector for decrypting the validation data |
| `documents (Decrypted documents).document_1.validation_data (Encrypted validation data).mac` | string | The message authentication code for the encrypted validation data payload |
| `documents (Decrypted documents).document_1.validation_data (Encrypted validation data).data` | string | The encrypted validation data |
| `documents (Decrypted documents).document_2` | object | Details from the second document (see document_1 for details) |
| `documents (Decrypted documents).document_3` | object | Details from the third document (see document_1 for details) |
| `documents (Decrypted documents).id_photo` | object | Details from the user supplied ID photo |
| `documents (Decrypted documents).id_photo.biometric_result` | object | The result of biometric comparison, empty if no liveness performed |
| `documents (Decrypted documents).id_photo.biometric_result.similarity` | number | Similarity percentage between the probe image from the liveness check and the ID photo Example: `98.8764` |
| `documents (Decrypted documents).id_photo.biometric_result.passed` | boolean | If the biometric similarity is sufficient to pass the biometric pass threshold Example: `true` |
| `documents (Decrypted documents).id_photo.biometric_result.threshold` | number | The biometric pass threshold percentage Example: `80` |
| `images` | object | The images captured during the check including the liveness probe image and any document images. |
| `images.probe_image` | one of 2 shapes | One of: Decrypted probe image; Encrypted probe image. The probe image captured during the liveness check (if liveness was requested) When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted probe image: The probe image in base64 encoded JPEG format (string) |
| `images.probe_image (Encrypted probe image).iv` | string | The initialisation vector for decrypting the probe image |
| `images.probe_image (Encrypted probe image).mac` | string | The message authentication code for the encrypted probe image payload |
| `images.probe_image (Encrypted probe image).data` | string | The encrypted probe image |
| `images.document_1` | object | Images from document 1 |
| `images.document_1.front` | one of 2 shapes | One of: Decrypted front image; Encrypted front image. The front image for document 1 When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted front image: The front image in base64 encoded JPEG format (string) |
| `images.document_1.front (Encrypted front image).iv` | string | The initialisation vector for decrypting the front image |
| `images.document_1.front (Encrypted front image).mac` | string | The message authentication code for the encrypted front image payload |
| `images.document_1.front (Encrypted front image).data` | string | The encrypted front image |
| `images.document_1.back` | one of 2 shapes | One of: Decrypted back image; Encrypted back image. The back image for documents with a back side, eg licence When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted back image: The back image in base64 encoded JPEG format (string) |
| `images.document_1.back (Encrypted back image).iv` | string | The initialisation vector for decrypting the back image |
| `images.document_1.back (Encrypted back image).mac` | string | The message authentication code for the encrypted back image payload |
| `images.document_1.back (Encrypted back image).data` | string | The encrypted back image |
| `images.document_1.photo` | one of 2 shapes | One of: Decrypted photo image; Encrypted photo image. The photo image for document types with a photo, eg licence, passport, visa When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted photo image: The photo image in base64 encoded JPEG format (string) |
| `images.document_1.photo (Encrypted photo image).iv` | string | The initialisation vector for decrypting the photo image |
| `images.document_1.photo (Encrypted photo image).mac` | string | The message authentication code for the encrypted photo image payload |
| `images.document_1.photo (Encrypted photo image).data` | string | The encrypted photo image |
| `images.document_2` | object | Images from document 2 |
| `images.document_2.front` | one of 2 shapes | One of: Decrypted front image; Encrypted front image. The front image for document 2 When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted front image: The front image in base64 encoded JPEG format (string) |
| `images.document_2.front (Encrypted front image).iv` | string | The initialisation vector for decrypting the front image |
| `images.document_2.front (Encrypted front image).mac` | string | The message authentication code for the encrypted front image payload |
| `images.document_2.front (Encrypted front image).data` | string | The encrypted front image |
| `images.document_2.back` | one of 2 shapes | One of: Decrypted back image; Encrypted back image. The back image for documents with a back side, eg licence When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted back image: The back image in base64 encoded JPEG format (string) |
| `images.document_2.back (Encrypted back image).iv` | string | The initialisation vector for decrypting the back image |
| `images.document_2.back (Encrypted back image).mac` | string | The message authentication code for the encrypted back image payload |
| `images.document_2.back (Encrypted back image).data` | string | The encrypted back image |
| `images.document_2.photo` | one of 2 shapes | One of: Decrypted photo image; Encrypted photo image. The photo image for document types with a photo, eg licence, passport, visa When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted photo image: The photo image in base64 encoded JPEG format (string) |
| `images.document_2.photo (Encrypted photo image).iv` | string | The initialisation vector for decrypting the photo image |
| `images.document_2.photo (Encrypted photo image).mac` | string | The message authentication code for the encrypted photo image payload |
| `images.document_2.photo (Encrypted photo image).data` | string | The encrypted photo image |
| `images.document_3` | object | Images from document 2 |
| `images.document_3.front` | one of 2 shapes | One of: Decrypted front image; Encrypted front image. The front image for document 3 When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted front image: The front image in base64 encoded JPEG format (string) |
| `images.document_3.front (Encrypted front image).iv` | string | The initialisation vector for decrypting the front image |
| `images.document_3.front (Encrypted front image).mac` | string | The message authentication code for the encrypted front image payload |
| `images.document_3.front (Encrypted front image).data` | string | The encrypted front image |
| `images.document_3.back` | one of 2 shapes | One of: Decrypted back image; Encrypted back image. The back image for documents with a back side, eg licence When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted back image: The back image in base64 encoded JPEG format (string) |
| `images.document_3.back (Encrypted back image).iv` | string | The initialisation vector for decrypting the back image |
| `images.document_3.back (Encrypted back image).mac` | string | The message authentication code for the encrypted back image payload |
| `images.document_3.back (Encrypted back image).data` | string | The encrypted back image |
| `images.document_3.photo` | one of 2 shapes | One of: Decrypted photo image; Encrypted photo image. The photo image for document types with a photo, eg licence, passport, visa When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted photo image: The photo image in base64 encoded JPEG format (string) |
| `images.document_3.photo (Encrypted photo image).iv` | string | The initialisation vector for decrypting the photo image |
| `images.document_3.photo (Encrypted photo image).mac` | string | The message authentication code for the encrypted photo image payload |
| `images.document_3.photo (Encrypted photo image).data` | string | The encrypted photo image |
| `images.id_photo` | one of 2 shapes | One of: Decrypted ID photo image; Encrypted ID photo image. The ID photo image provided by the user (if requested) When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted ID photo image: The ID photo image in base64 encoded JPEG format (string) |
| `images.id_photo (Encrypted ID photo image).iv` | string | The initialisation vector for decrypting the ID photo image |
| `images.id_photo (Encrypted ID photo image).mac` | string | The message authentication code for the encrypted ID photo image payload |
| `images.id_photo (Encrypted ID photo image).data` | string | The encrypted ID photo image |
| `images.id_photo_cropped` | one of 2 shapes | One of: Decrypted cropped ID photo image; Encrypted cropped ID photo image. The cropped ID photo image (if requested) When a cipher_key is provided this image is decrypted; otherwise the encrypted payload is returned for local decryption. Decrypted cropped ID photo image: The cropped ID photo image in base64 encoded JPEG format (string) |
| `images.id_photo_cropped (Encrypted cropped ID photo image).iv` | string | The initialisation vector for decrypting the cropped ID photo image |
| `images.id_photo_cropped (Encrypted cropped ID photo image).mac` | string | The message authentication code for the encrypted cropped ID photo image payload |
| `images.id_photo_cropped (Encrypted cropped ID photo image).data` | string | The encrypted cropped ID photo image |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "id": "00000000-0000-0000-0000-000000000000",
    "link": "https://idpass.globaldata.net.au/idpass?token=abcd123456",
    "status": "new",
    "verification_status": "passed",
    "verification_description": "Document 1 had biographic identity edits before verification\nThe identity was verified successfully",
    "config": {
        "link_validity_days": 3,
        "image_retention_days": 5,
        "check_liveness": true,
        "document_1_allowed_types": [
            "licence",
            "passport"
        ],
        "document_2_allowed_types": [],
        "document_3_allowed_types": [],
        "webhook_url": "https://example.com/webhook",
        "webhook_events": [
            "complete"
        ],
        "return_url": "https://example.com/return",
        "privacy_policy_url": "https://example.com/privacy",
        "requester_name": "Sample Company",
        "requested_identity": {
            "first_name": "John",
            "middle_name": "Andrew",
            "last_name": "Smith",
            "date_of_birth": "1990-03-21"
        }
    },
    "created_at": "2024-05-16T01:26:08+00:00",
    "consent_given_at": "2024-05-16T01:35:11+00:00",
    "consent_text": "I confirm that I am authorised to provide my personal details...",
    "completed_at": "2024-05-16T01:38:28+00:00",
    "ip_address": "203.22.251.3",
    "logs": [
        "2024-05-16T01:31:23+00:00 - 203.22.251.3 - Starting IdPass flow",
        "2024-05-16T01:35:11+00:00 - 203.22.251.3 - Consent given"
    ],
    "validation_summary": {
        "document_verification": "dvs",
        "liveness_result": {
            "validated": true,
            "confidence": "99.811",
            "liveness_attempts": 1,
            "bounding_box": {
                "top": 0.1,
                "left": 0.1,
                "width": 0.1,
                "height": 0.1
            }
        },
        "id_photo_result": {
            "status": "complete",
            "bounding_box": {
                "top": 0.1,
                "left": 0.1,
                "width": 0.1,
                "height": 0.1
            },
            "image_passed": true,
            "biometric_passed": true
        },
        "document_1_result": {
            "document_type": "licence",
            "validated_fields": {
                "first_name": "John",
                "middle_name": "Andrew",
                "last_name": "Smith",
                "date_of_birth": "1990-03-21",
                "partial_date_of_birth": "1980-03",
                "full_name": "John Smith"
            },
            "biographic_validated": true,
            "biometric_validated": true,
            "biometric_similarity": "99.804",
            "biometric_threshold": 80,
            "changes": {
                "passport_number": {
                    "from": "PB6015447",
                    "to": "M1000000"
                }
            }
        },
        "verified_identity": {
            "first_name": "John",
            "middle_name": "Andrew",
            "last_name": "Smith",
            "date_of_birth": "1990-03-21",
            "partial_date_of_birth": "1980-03"
        },
        "requested_identity_mismatch": false
    },
    "documents": {
        "document_1": {
            "document_type": "licence",
            "document_number": 1,
            "ocr_status": "complete",
            "ocr_attempts": 1,
            "validation_status": "complete",
            "validation_result": {
                "strategy": "dvs",
                "verification_result_code": "Y",
                "verification_request_number": "7a3ed6e1-b707-4e2d-bacb-e2dfe8f57406",
                "additional_information": [
                    {
                        "code": "DL-006",
                        "message": "Card number not matched."
                    }
                ],
                "originating_agency_code": "DVS123",
                "checked_at": "2026-04-16 04:28:53"
            },
            "validation_attempts": 1,
            "biometric_result": {
                "passed": true,
                "threshold": 80,
                "similarity": 98.8764,
                "face_occluded": false
            },
            "ocr_data": {
                "first_name": "example value",
                "last_name": "example value",
                "date_of_birth": "1990-03-21"
            },
            "validation_data": {
                "first_name": "example value",
                "last_name": "example value",
                "date_of_birth": "1990-03-21",
                "partial_date_of_birth": "1980-03",
                "registration_number": "0100234",
                "registration_number_as_entered": "1/234/56X",
                "district_number_confirmed": "01"
            }
        },
        "id_photo": {
            "biometric_result": {
                "similarity": 98.8764,
                "passed": true,
                "threshold": 80
            }
        }
    },
    "images": {
        "probe_image": "string",
        "document_1": {
            "front": "string",
            "back": "string",
            "photo": "string"
        },
        "document_2": {
            "front": "string",
            "back": "string",
            "photo": "string"
        },
        "document_3": {
            "front": "string",
            "back": "string",
            "photo": "string"
        },
        "id_photo": "string",
        "id_photo_cropped": "string"
    }
}
```

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