# Create an ID Pass

`POST /idpass/register`

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

## ID Pass

Please review the full ID Pass documentation here:

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

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](/docs/guides/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

The configuration for the ID Pass to create

| Field | Type | 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` |

**Sample request**

```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"
    }
}
```

## Responses

### 200 Details of the newly created 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. |
| `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` |

**Sample response**

```json
{
    "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"
}
```

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