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." Every webhook is signed with the webhook_secret returned by this endpoint, so you can check it came from Global Data. See Webhook signature verification.
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

In the sandbox environment the DVS checks are simulated, and the result (pass, fail, etc) is determined by the document number, in the same way as other sandbox DVS queries.

Your account does not need a DVS Identity (OAC) to use the sandbox. If you do send the oac field, it must be one of your account's own identities or one of the sample identities below. Any other value is rejected.

The sample identities let you see how an ID Pass registered on behalf of another organisation appears to the end user, before your own additional identities are set up. Each one shows its own organisation name and privacy policy link on the consent screen:

`oac`	Organisation name	Privacy policy URL
`SANDBOX1`	Sample Organisation One	https://example.com/sample-org-one/privacy
`SANDBOX2`	Sample Organisation Two	https://example.com/sample-org-two/privacy
`SANDBOX3`	Sample Organisation Three	https://example.com/sample-org-three/privacy

The sample identities work in the sandbox only and are rejected in the live environment.

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..90] or null Number of days for which the link should remain available, from 1 to 90 days. 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. The retention period is counted from the time the ID Pass reaches a final status (complete, failed, cancelled or expired), not from when it was registered. An ID Pass that is never finished only reaches its final status when the link expires, so its images are retained for the link validity period plus the retention period. A setting of 0 will cause the images to be deleted as soon as the ID Pass reaches a final status and prevents the ID Pass Details endpoint from ever returning image data for the check. Images are deleted automatically by a daily process once the retention period has passed. Only the images are deleted - the ID Pass record, verification results and document details are retained and remain available from the ID Pass Details endpoint. All personal information in the retained record (the requested identity, validation summary, document OCR data and document validation data) is stored encrypted with the cipher_key returned by this endpoint. Global Data holds the cipher_key only while the check is in progress and discards it once the ID Pass reaches a final status, so from that point the retained data can only be decrypted using your copy of the cipher_key. If you delete your copy of the cipher_key the personal information in the ID Pass is no longer retrievable by anyone, including Global Data. Non-personal metadata such as the status, verification outcome, configuration and timestamps remains readable without the cipher_key. 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) for live environments: the account's own, or one of its additional identities selected with the `oac` field. `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`
`oac`	string [4..20 characters] or null The DVS Identity (Originating Agency Code) to register the ID Pass under. You only need this if Global Data has set up additional DVS Identities on your account, for example because you register ID Passes on behalf of other organisations. If you leave it out, your account's own DVS Identity is used. If you send it, it must be your account's own DVS Identity or one of its additional identities. Any other value is rejected. The identity decides what the end user sees. An ID Pass registered under an additional identity shows that organisation's name and privacy policy on the consent screen, and its DVS checks run under that organisation's code. If your account has additional identities but no DVS Identity of its own, this field is required whenever the ID Pass includes documents checked with the DVS. In the sandbox you can also use the sample identities `SANDBOX1`, `SANDBOX2` and `SANDBOX3` (see "Sandbox environment" above). Example: `ABC1`
`webhook_url`	string (url) or null Webhook URL which the ID Pass system will call to notify events. Must be an `https` URL whose host resolves to a public internet address. Redirects are not followed when the webhook is delivered. 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 for this ID Pass. All personal information captured during the check is encrypted with this key. Global Data discards the key once the ID Pass reaches a final status, so store it securely - it is the only way to decrypt the ID Pass data afterwards, and it is never returned again. Example: `IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA=`
`webhook_secret`	string The secret used to sign this ID Pass's webhooks. Each webhook has a `Signature` header, which is the HMAC SHA-256 hex digest of the request body using this secret as the key. Store it with the ID Pass so you can verify its webhooks. It is also returned by `idpass/details`. Example: `3f9c1b7e4d2a6c8f0b5e9d1a7c3f6b2e8d4a0c9f1e7b3d5a2c8e6f4b0d9a1c3e`
`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",
    "oac": "ABC1",
    "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=",
    "webhook_secret": "3f9c1b7e4d2a6c8f0b5e9d1a7c3f6b2e8d4a0c9f1e7b3d5a2c8e6f4b0d9a1c3e",
    "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"
}