Launch an adhoc ID check

POST /api/v1/adhoc-id-checks operationId: adhoc-id-check.launch

Base: https://portal.watcheye.com.au/api/v1/adhoc-id-checks

Runs a synchronous quick ID check and returns 200 OK with the full completed payload. See launch entity ID check for consent, idempotency and billing behaviour.

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
`id_type`required	string Identification type to run. See SELECTABLE_ID_TYPES in the portal field reference. Example: `drivers_licence`
`consent_obtained`required	boolean Must be `true`. Asserts that your system has obtained express, demonstrable consent from the individual being verified before this check is launched, and that the exact wording shown has been retained by your system for audit and compliance purposes. The specific wording you must show and the records you must keep depend on which check types you run and the regulatory regime you operate under. For DVS-based check types your consent must align with your account's DVS Agreement with the Australian Government, which prescribes specific disclosure and record-keeping requirements. See the Consent section of the API guide for your full obligations and an illustrative starting point for the wording.
`data`required	object Per-type input fields inside the launch request. Document numbers are never returned in responses. Date of birth must be supplied as `birth_date` in `YYYY-MM-DD` format when required for the selected `id_type`. Other date fields (`card_expiry`, `acquisition_date`, `event_date`, `registration_date`) also use `YYYY-MM-DD`; month-only fields (e.g. Medicare and ASIC/MSIC `card_expiry`) use `YYYY-MM`. See the per-id_type tables in the API guide for the exact fields and formats accepted by each check.
`data.birth_date`	string (date) Date of birth in `YYYY-MM-DD` format. Example: `1980-06-23`
`oac`	string or null The DVS OAC code to use for this check. Must be one of the OAC codes configured on your account. 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`

Responses

200

Adhoc ID check completed

application/json

Field Description

data

object

A quick (adhoc) identification check not tied to an entity.

data.uuid string (uuid)

data.check_number string

data.id_type string

data.id_type_name string

data.check_type string

data.check_type_name string

data.outcome

string

Enum: pass, fail, pending

data.outcome_summary string or null

data.data_summary string or null

data.checked_at string (date-time) or null

data.created_by

object or null

Identifies who launched the adhoc ID check. The type discriminator picks the shape of the remaining fields:

{ type: "user", uuid, username } - a portal user launched the check.
{ type: "api_key", uuid, label } - an API key on this account launched the check.
null - rare legacy rows from before actor attribution was recorded.

data.created_by.type

string

Discriminator for the actor type.

Enum: user, api_key

data.created_by.uuid

string (uuid)

UUID of the user or API key that launched the check.

data.created_by.username

string

Username of the portal user. Present only when type is user.

data.created_by.label

string

Label of the API key. Present only when type is api_key.

data.idpass

object

Present only when id_type is idpass. A lightweight shell of the linked IDPass plus idpass_url, the path to the full IDPass resource.

data.idpass.uuid

string (uuid)

The IDPass identifier. Use it with the show, image and PDF endpoints.

Example: 5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a

data.idpass.status

string

Where the individual is in the hosted flow:

new - the link has not been opened
opened - the welcome page was passed
in_progress - consent was given and documents are being submitted
complete - the verification finished; read verification_status for the outcome
expired - link_validity_days elapsed before completion
failed - the verification could not be completed
cancelled - cancelled in the portal

The last four are terminal. See the IDPass section of the guide.

Enum: new, opened, in_progress, complete, expired, failed, cancelled

Example: in_progress

data.idpass.verification_status

string or null

The outcome once status is terminal, null until then:

passed - the identity was verified
review - the identity was verified but flagged for review in the portal; treat it as not yet passed
failed - the identity was not verified (including an expired or cancelled IDPass)

Enum: passed, review, failed

Example: passed

data.idpass.idpass_link

string or null

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.idpass.idpass_url

string

Path to the full IDPass resource (GET /v1/idpasses/{uuid}).

Example: /v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a

data.consent object (dynamic)

data.verification_details array of objects

data.verification_details[].field string

data.verification_details[].value string

data.details one of 6 shapes

object 1

Field	Description
`verification_result_code`	string Enum: `Y`, `N`, `D`
`originating_agency_code`	string or null
`verification_request_number`	string or null
`additional_information`	array of strings

object 2

Field	Description
`api_reference`	string or null
`message`	string or null
`match_results`	object or null
`match_results.first_name`	string
`match_results.last_name`	string
`match_results.dob`	string Date of birth match result from the upstream provider.

object 3

Field	Description
`api_reference`	string or null
`person_match`	string or null

object 4

Field	Description
`api_reference`	string or null
`reporting_reference`	string or null Unique transaction identifier from the data source.
`match_status`	string or null Overall match result. `Match` indicates the supplied identity was fully verified. Enum: `Match`, `NoMatch`
`document_verified`	boolean Whether NZTA reports the supplied licence details as verified.
`additional_information`	string or null Explanatory message returned by the data source, typically alongside a `NoMatch` result.

object 5

Field	Description
`api_reference`	string or null
`reporting_reference`	string or null Unique transaction identifier from the data source.
`match_status`	string or null Overall match result. `Match` indicates the supplied identity was fully verified. Enum: `Match`, `NoMatch`
`document_verified`	boolean Whether the NZ Department of Internal Affairs (DIA) reports the supplied passport details as verified.
`additional_information`	string or null Explanatory message returned by the data source, typically alongside a `NoMatch` result.

object 6

Field	Description
`api_reference`	string or null
`payroll_person`	string or null
`super_person`	string or null

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 429 5XX See common error responses

Previous List adhoc ID checks Next Show an adhoc ID check

Request body application/json

{
    "id_type": "drivers_licence",
    "consent_obtained": true,
    "data": {
        "birth_date": "1980-06-23"
    },
    "oac": "ABC123"
}

Response

200 Adhoc ID check completed

{
    "data": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "check_number": "string",
        "id_type": "string",
        "id_type_name": "string",
        "check_type": "string",
        "check_type_name": "string",
        "outcome": "pass",
        "outcome_summary": "string",
        "data_summary": "string",
        "checked_at": "2024-01-01T00:00:00Z",
        "created_by": {
            "type": "user",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "username": "string",
            "label": "string"
        },
        "idpass": {
            "uuid": "5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a",
            "status": "in_progress",
            "verification_status": "passed",
            "idpass_link": "https://idpass.globaldata.net.au/idpass?token=abcd123456",
            "idpass_url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a"
        },
        "verification_details": [
            {
                "field": "string",
                "value": "string"
            }
        ],
        "details": {
            "verification_result_code": "Y",
            "originating_agency_code": "string",
            "verification_request_number": "string",
            "additional_information": [
                "string"
            ]
        }
    },
    "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"
}

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