Create an ID Pass

POST /api/v2/idpass/register operationId: idpass_register

Live: https://gdapi.globaldata.net.au/api/v2/idpass/register · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/idpass/register

ID Pass

Please review the full ID Pass documentation here:

ID Pass documentation

ID Pass is powerful and secure platform for verifying customer identities in compliance with KYC and AML regulations. The API provides an efficient way to integrate identity verification workflows into your applications, ensuring smooth user experiences while maintaining the highest security and data privacy standards.

Document Verification: Supports Australian Driver's Licenses, Passports, Foreign Passports with an Australian Visa, Centrelink Cards, Medicare Cards, Australian Birth Certificates and New Zealand Driver Licences. Integrates with the Australian Document Verification Service (DVS) for Australian documents and with the New Zealand licence issuer for New Zealand Driver Licences.
Biometric Face Verification: Liveness detection ensures authenticity. Matches selfies to the ID document for added security.
Secure and Configurable: Fully encrypted data storage and transfer. Configurable link validity, retention settings, and webhook notifications.

API Workflow

Create an ID Pass: Generate a secure verification link for your users with customizable configurations. Control parameters such as allowed document types, liveness checks, and link expiration.
Monitor Progress: Use webhooks to track verification events such as "in_progress," "complete," or "failed."
Retrieve Results: Access detailed verification results, including document validation, biometric comparison, and logs. Optionally decrypt sensitive information locally using a provided cipher key.

Sandbox environment

When creating an ID Pass in the sandbox environment, the actual DVS checks for the identity documents will be simulated and the specific result (pass, fail, etc) will determined by the ID number in the same way as other sandbox DVS queries.

Sample documents are available for you to test with the ID Pass API:

DVS sample documents

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.

Request body

Content type application/json. The configuration for the ID Pass to create

Field	Description
`link_validity_days`	integer [1..14] or null Number of days for which the link should remain available Default: `7` Example: `3`
`image_retention_days`	integer [0..365] or null Number of days for which the images from the check will be stored, up to a maximum of 365 days. The stored images include the probe image from the face liveness check (if liveness was requested) and the front / back /photo images from any identity documents used during the check. A setting of 0 will cause the images to be deleted once the check has been completed and prevents the ID Pass Details endpoint from ever returning image data for the check. Images are deleted automatically once the retention period has passed. Default: `0` Example: `5`
`check_liveness`	boolean or null Whether a face liveness check should be performed. Default: `false` Example: `true`
`document_1_allowed_types`	array of strings or null The types of documents which are allowed for the first document check. `licence` - Australian Drivers Licence `passport` - Australian Passport `medicare` - Medicare Card `visa` - Foreign Passport (for Australian Visa holders) `centrelink` - Centrelink Card (manual entry, no OCR) `birth_certificate` - Australian Birth Certificate (manual entry, no OCR) `nz_licence` - New Zealand Driver Licence (front and back). Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence`
`document_2_allowed_types`	array of strings or null The types of documents which are allowed for the second document check. `licence` - Australian Drivers Licence `passport` - Australian Passport `medicare` - Medicare Card `visa` - Foreign Passport (for Australian Visa holders) `centrelink` - Centrelink Card (manual entry, no OCR) `birth_certificate` - Australian Birth Certificate (manual entry, no OCR) `nz_licence` - New Zealand Driver Licence (front and back). Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence`
`document_3_allowed_types`	array of strings or null The types of documents which are allowed for the third document check. `licence` - Australian Drivers Licence `passport` - Australian Passport `medicare` - Medicare Card `visa` - Foreign Passport (for Australian Visa holders) `centrelink` - Centrelink Card (manual entry, no OCR) `birth_certificate` - Australian Birth Certificate (manual entry, no OCR) `nz_licence` - New Zealand Driver Licence (front and back). Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence`
`document_verification`	string or null The verification strategy to use for identity documents. `dvs` - Full verification of Australian documents via the Australian Document Verification Service (DVS); a New Zealand Driver Licence is verified with the New Zealand licence issuer and returned in the same result shape. Requires a DVS Identity (OAC) on the account for live environments. `basic` - Basic format validation only. Checks that document fields match the expected format (e.g. card number patterns, Medicare checksums) without performing a DVS check. Does not require a DVS Identity. `idsp` - Identity Service Provider mode. Document verification is performed by Global Data on the customer's behalf. Requires liveness detection to be enabled and the account to be enrolled as an IDSP Service Client. Does not require a DVS Identity (OAC) on the account. Enum: `dvs`, `basic`, `idsp` Default: `dvs` Example: `dvs`
`require_id_photo`	boolean or null Whether the user should be required to supply an ID photo. Default: `false` Example: `true`
`id_photo_purpose`	string [3..255 characters] or null The purpose of the ID photo. This text will be included on the page where the user is asked to supply the ID photo. For example, passing "the SampleCo Membership Card" will display the text "This image will be used for the SampleCo Membership Card" on the page where the user is asked to supply the ID photo. Note that the id_photo_purpose is required if require_id_photo is true and must be between 3 and 255 characters. Example: `the SampleCo Membership Card`
`webhook_url`	string (url) or null Webhook URL which the ID Pass system will call to notify events Example: `https://example.com/webhook`
`webhook_events`	array of strings or null The events for which the webhook should be called `opened` - Opened `in_progress` - In Progress `complete` - Completed `expired` - Expired `failed` - Failed `cancelled` - Cancelled Enum: `opened`, `in_progress`, `complete`, `expired`, `failed`, `cancelled`
`return_url`	string (url) or null URL to link to from the ID Pass complete page. This can be used to return the user to your application or website after they complete the ID Pass.
`requested_identity`	object or null Optional object containing your customer's identity details to be verified. At least one of `first_name` or `last_name` must be provided when this object is supplied. `middle_name` alone is not valid. During verification comparison, a submitted single hyphen (`-`) for first or last name is treated as missing for matching against missing requested identity values.
`requested_identity.first_name`	string or null Optional first name of your customer to be verified. Provide `first_name`, `last_name`, or both. Example: `John`
`requested_identity.middle_name`	string or null Optional middle name of your customer to be verified. This field does not satisfy the required-name rule on its own. Example: `Andrew`
`requested_identity.last_name`	string or null Optional last name of your customer to be verified. Provide `first_name`, `last_name`, or both. Example: `Johnson`
`requested_identity.date_of_birth`	string (date) or null Optional date of birth of your customer to be verified. If provided, this is matched against the verified identity date of birth. If omitted or null, only name matching is performed and you should verify the returned `verified_identity.date_of_birth` yourself. Example: `1980-01-01`

Responses

200

Details of the newly created ID Pass

application/json

Field	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.
`cipher_key`	string The cipher key fot this ID Pass. All PII will be encrypted with this key. Example: `IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA=`
`link`	string (url) The ID Pass link to be provided to your user Example: `https://idpass.globaldata.net.au/idpass?token=abcd123456`

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Extract ID Document Data & Face Image Next Read an ID Pass

Request body application/json

{
    "link_validity_days": 3,
    "image_retention_days": 5,
    "check_liveness": true,
    "document_1_allowed_types": [
        "licence",
        "passport"
    ],
    "document_2_allowed_types": [
        "licence",
        "passport"
    ],
    "document_3_allowed_types": [
        "licence",
        "passport"
    ],
    "document_verification": "dvs",
    "require_id_photo": true,
    "id_photo_purpose": "the SampleCo Membership Card",
    "webhook_url": "https://example.com/webhook",
    "webhook_events": [
        "opened"
    ],
    "return_url": "https://example.com",
    "requested_identity": {
        "first_name": "John",
        "middle_name": "Andrew",
        "last_name": "Johnson",
        "date_of_birth": "1980-01-01"
    }
}

Response

200 Details of the newly created ID Pass

{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "id": "00000000-0000-0000-0000-000000000000",
    "cipher_key": "IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA=",
    "link": "https://idpass.globaldata.net.au/idpass?token=abcd123456"
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}