Launch an IDPass against an entity

POST /api/v1/entities/{entity_uuid}/idpasses operationId: idpass.launch

Base: 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 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 section.

Path parameters

Field	Description
`entity_uuid`required	string (uuid) The uuid of the entity.

Header parameters

Field Description

Field	Description
`Idempotency-Key`	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 section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f`

Idempotency-Key

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 section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json.

Field	Description
`data`required	object 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`required	object How the hosted verification runs. The keys listed as required must all be supplied.
`config.link_validity_days`required	integer [1..14] 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`required	boolean 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`required	array of strings [min 1 items] 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`required	boolean 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`required	boolean Whether the verification images should be retained and made available for download afterwards via the IDPass image endpoint. Example: `true`
`config.delivery_method`required	string 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`

Responses

202

IDPass created - poll the show endpoint for the asynchronous result

application/json

Field	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 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)

422

Idempotency-Key was reused with a different request body

application/json

Field	Description
`message`	string

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

Previous Show an IDPass Next Launch an adhoc IDPass

Request body application/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"
    }
}

Response

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

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

400 Bad Request - The request is invalid shared error response

{
    "message": "Bad Request",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "errors": {
        "data.passport_number": [
            "The passport number format is invalid."
        ]
    }
}

401 Unauthorized - the API key or account is inactive, expired, or not permitted from this IP address shared error response

{
    "message": "API Key Inactive",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

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

{
    "message": "Insufficient Credit",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

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

{
    "message": "No access",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

404 Not Found - The requested resource does not exist or is not accessible by this account shared error response

{
    "message": "Entity not found",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

422 Idempotency-Key was reused with a different request body

{
    "message": "string"
}

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

{
    "message": "Rate limited",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}