# Launch an IDPass against an entity

`POST /entities/{entity_uuid}/idpasses`

- Base: `POST https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/idpasses`

Creates a remote identity verification (IDPass) for a saved individual entity and returns
**202 Accepted** with the IDPass shell, including its hosted `idpass_link`. The entity must
be an individual. `data.dob` is optional - when supplied it must match the entity's recorded
date of birth, and when omitted the identity documents are still fully DVS-verified but the
supplied details are matched against the documents on name only.

The verification itself is completed by the individual on the hosted platform, so the
result is updated asynchronously. Poll [show IDPass](/docs/reference/idpass.show) until `status`
is terminal.

Each launch is charged at creation time. The product billed depends on the number of
document verification steps configured (`document_1`/`document_2`/`document_3`).

## Account requirements

Your account needs the IDPass product, and a DVS identity (OAC) with a privacy policy URL
configured: the OAC supplies the `requester_name` and `privacy_policy_url` shown to the
individual on the consent page. A launch that fails one of these returns `403`; insufficient
credit returns `402`; an invalid `config` (for example a step that reuses a document type
from an earlier step) returns `400`.

## Delivery

When `config.delivery_method` is `sms`, the hosted link is sent to `config.delivery_phone`.
When it is `manual`, no message is sent and you are responsible for delivering `idpass_link`
to the individual.

## Idempotency

Accepts the `Idempotency-Key` header. See the
[Idempotency](/docs/guides/watcheye_api/idempotency) section.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `entity_uuid` | path | string (uuid) | **Required.** The uuid of the entity. |
| `Idempotency-Key` | header | string [max 255 characters] | Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the [Idempotency](/docs/guides/watcheye_api/idempotency) section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f` |

## Request body

| Field | Type | Description |
|-------|------|-------------|
| `data` | object | **Required.** The identity being verified. The name and date of birth the individual's documents establish are compared against these. |
| `data.first_name` | string [max 50 characters] | Required unless `last_name` is supplied. Example: `John` |
| `data.middle_name` | string [max 50 characters] or null | Optional. Does not satisfy the name requirement on its own. Example: `Andrew` |
| `data.last_name` | string [max 50 characters] | Required unless `first_name` is supplied. Example: `Smith` |
| `data.dob` | string (date) or null | Date of birth in `YYYY-MM-DD` format. Optional - when omitted, the identity documents are still fully DVS-verified, but the supplied details are matched against the documents on name only. For an entity-bound launch a supplied date of birth must match the entity's recorded date of birth. Example: `1980-06-23` |
| `oac` | string or null | The DVS OAC code the IDPass should be issued under. Must be one of the OAC codes configured on your account. The selected OAC determines the requesting organisation name and privacy policy shown to the person being verified. Required when your account is configured with more than one OAC. When your account has a single OAC this may be omitted and that OAC is used. Example: `ABC123` |
| `config` | object | **Required.** How the hosted verification runs. The keys listed as required must all be supplied. |
| `config.link_validity_days` | integer [1..14] | **Required.** How many days the hosted link stays open, from 1 to 14. When it lapses the IDPass moves to `expired`, and the launch charge is refunded if the link was never used. Example: `7` |
| `config.check_liveness` | boolean | **Required.** Whether to perform a face liveness check. The selfie it captures is also compared biometrically against the photo on each document that has one. Example: `true` |
| `config.document_1_allowed_types` | array of strings [min 1 items] | **Required.** The document types the individual may present for the first verification step: * `licence` - Australian driver licence * `passport` - Australian passport * `medicare` - Medicare card * `visa` - foreign passport with an Australian visa * `centrelink` - Centrelink card (details typed in, no photo) * `birth_certificate` - Australian birth certificate (details typed in, no photo) * `nz_licence` - New Zealand driver licence Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `config.document_2_allowed_types` | array of strings | Optional second verification step. Requires document 1 to be supplied, and a step cannot reuse a document type already consumed by an earlier step. The same document types as the first step: * `licence` - Australian driver licence * `passport` - Australian passport * `medicare` - Medicare card * `visa` - foreign passport with an Australian visa * `centrelink` - Centrelink card (details typed in, no photo) * `birth_certificate` - Australian birth certificate (details typed in, no photo) * `nz_licence` - New Zealand driver licence Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `config.document_3_allowed_types` | array of strings | Optional third verification step. Requires document 2 to be supplied, and a step cannot reuse a document type already consumed by an earlier step. The same document types as the first step: * `licence` - Australian driver licence * `passport` - Australian passport * `medicare` - Medicare card * `visa` - foreign passport with an Australian visa * `centrelink` - Centrelink card (details typed in, no photo) * `birth_certificate` - Australian birth certificate (details typed in, no photo) * `nz_licence` - New Zealand driver licence Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `config.require_id_photo` | boolean | **Required.** Whether the individual must also supply a standalone ID photo, for example for a membership card. Example: `true` |
| `config.id_photo_purpose` | string [3..255 characters] or null | Required when `require_id_photo` is `true`. Shown to the individual on the ID photo page to complete the sentence "This image will be used for ...", so write it to follow "for". Example: `the SampleCo Membership Card` |
| `config.return_url` | string (uri) or null | A URL to offer the individual once the verification is complete, for example to return them to your application. Example: `https://example.com/verification-complete` |
| `config.return_verification_images` | boolean | **Required.** Whether the verification images should be retained and made available for download afterwards via the IDPass image endpoint. Example: `true` |
| `config.delivery_method` | string | **Required.** How the hosted link reaches the individual: * `sms` - WatchEye sends the link to `delivery_phone` by text message * `manual` - the link is only returned as `idpass_link` and you deliver it yourself In sandbox no text message is sent either way. Enum: `manual`, `sms` Example: `sms` |
| `config.delivery_phone` | string or null | Australian mobile number (04XXXXXXXX). Required when `delivery_method` is `sms`, in which case the hosted link is sent to this number. Example: `0412345678` |

**Sample request**

```json
{
    "data": {
        "first_name": "John",
        "middle_name": "Andrew",
        "last_name": "Smith",
        "dob": "1980-06-23"
    },
    "oac": "ABC123",
    "config": {
        "link_validity_days": 7,
        "check_liveness": true,
        "document_1_allowed_types": [
            "licence",
            "passport"
        ],
        "document_2_allowed_types": [
            "medicare"
        ],
        "document_3_allowed_types": [
            "passport"
        ],
        "require_id_photo": true,
        "id_photo_purpose": "the SampleCo Membership Card",
        "return_url": "https://example.com/verification-complete",
        "return_verification_images": true,
        "delivery_method": "sms",
        "delivery_phone": "0412345678"
    }
}
```

## Responses

### 202 IDPass created - poll the show endpoint for the asynchronous result

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object | A newly launched IDPass: its identifier, configuration, delivery details and the hosted link, plus the ID check it belongs to. The verification outcome, document and validation summaries, log and images do not exist yet - poll [show IDPass](/docs/reference/idpass.show) for them once the individual has completed the link. |
| `data.uuid` | string (uuid) | The IDPass identifier. Use it with the show, image and PDF endpoints. Example: `5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a` |
| `data.source` | string | Whether the IDPass is bound to a saved entity or was launched adhoc. Enum: `entity`, `adhoc` Example: `adhoc` |
| `data.requester_name` | string | Your organisation's name as shown to the individual on the consent page. It comes from the DVS identity (OAC) the IDPass was issued under. Example: `Sample Company Pty Ltd` |
| `data.check_liveness` | boolean | Whether the individual will be asked to complete a face liveness check. Example: `true` |
| `data.require_id_photo` | boolean | Whether the individual will be asked to supply a standalone ID photo. Example: `false` |
| `data.document_allowed_types` | object | The allowed document types for each of the (up to three) verification steps, as configured. |
| `data.document_allowed_types.document_1` | array of strings | Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data.document_allowed_types.document_2` | array of strings | Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data.document_allowed_types.document_3` | array of strings | Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data.link_validity_days` | integer | How many days the hosted link stays open before the IDPass expires. Example: `7` |
| `data.return_verification_images` | boolean | Whether verification images will be retained and made available for download. Example: `true` |
| `data.delivery_method` | string | How the link reaches the individual: * `sms` - WatchEye has sent it to `delivery_phone` by text message * `manual` - you deliver `idpass_link` yourself Enum: `manual`, `sms` Example: `sms` |
| `data.idpass_link` | string | The hosted link the individual opens to complete their verification. Treat it as opaque - pass it on as-is and do not parse or rebuild it. Example: `https://idpass.globaldata.net.au/idpass?token=abcd123456` |
| `data.sent_at` | string (date-time) or null | When the link was sent by SMS. Null when `delivery_method` is `manual`. Example: `2026-08-01T02:15:30+00:00` |
| `data.created_at` | string (date-time) | When the IDPass was launched. Example: `2026-08-01T02:15:28+00:00` |
| `data.detail_url` | string | Path to the full IDPass resource (GET /v1/idpasses/{uuid}). Poll it for the result. Example: `/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a` |
| `data.id_check` | object or null | The ID check this IDPass was created under (entity-bound or adhoc) plus a link to it. |
| `data.id_check.type` | string | Whether the ID check belongs to an entity or was adhoc. Enum: `entity`, `adhoc` Example: `adhoc` |
| `data.id_check.uuid` | string (uuid) | Example: `8a0d2f4e-6b1c-4e9a-b3d7-2c5e1f6a9b0d` |
| `data.id_check.check_number` | string | The ID check's reference number as shown in the portal. Example: `IDC-000123` |
| `data.id_check.url` | string | Path to the ID check resource. Example: `/v1/adhoc-id-checks/8a0d2f4e-6b1c-4e9a-b3d7-2c5e1f6a9b0d` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": {
        "uuid": "5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a",
        "source": "adhoc",
        "requester_name": "Sample Company Pty Ltd",
        "check_liveness": true,
        "require_id_photo": false,
        "document_allowed_types": {
            "document_1": [
                "licence"
            ],
            "document_2": [
                "medicare"
            ],
            "document_3": []
        },
        "link_validity_days": 7,
        "return_verification_images": true,
        "delivery_method": "sms",
        "idpass_link": "https://idpass.globaldata.net.au/idpass?token=abcd123456",
        "sent_at": "2026-08-01T02:15:30+00:00",
        "created_at": "2026-08-01T02:15:28+00:00",
        "detail_url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a",
        "id_check": {
            "type": "adhoc",
            "uuid": "8a0d2f4e-6b1c-4e9a-b3d7-2c5e1f6a9b0d",
            "check_number": "IDC-000123",
            "url": "/v1/adhoc-id-checks/8a0d2f4e-6b1c-4e9a-b3d7-2c5e1f6a9b0d"
        }
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

### 422 Idempotency-Key was reused with a different request body

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string |  |

**Sample response**

```json
{
    "message": "string"
}
```

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