Launch an ID check against an entity

POST /api/v1/entities/{entity_uuid}/id-checks operationId: id-check.launch

Base: https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/id-checks

Runs a synchronous identification check against a saved entity and returns 200 OK with the full completed check payload inline. Unlike screening checks, ID checks do not queue for background processing and do not expose a status field.

Each launch is charged at run time after a successful upstream verification call.

Consent

consent_obtained must be true. By sending this flag you assert that your system has obtained express, demonstrable consent from the individual being verified, and that the exact consent wording shown has been retained by your system for audit and compliance purposes. The specific wording and records required depend on the 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. See the Consent section of the API guide for your full obligations and an illustrative starting point.

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

ID check completed - full detail payload returned inline

application/json

Field Description

data

object

An entity-bound identification check (list envelope).

data.uuid string (uuid)

data.check_number

string

Example: I-A1B2CD

data.id_type

string

Example: drivers_licence

data.id_type_name

string

Example: Drivers Licence

data.check_type

string

Example: drivers_licence_dvs

data.check_type_name

string

Example: Drivers Licence (DVS)

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.archived_at

string (date-time) or null

ISO 8601 timestamp at which the identification check was archived (null if not archived)

data.program object or null

data.program.uuid string (uuid)

data.program.program_name string

data.entity object or null

data.entity.uuid string (uuid)

data.entity.entity_number string

data.entity.entity_name string

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. Fetch that resource for the complete configuration, status, document/validation summaries and image metadata.

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

Previous Download an ID check certificate as PDF Next List IDPasses

Request body application/json

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

Response

200 ID check completed - full detail payload returned inline

{
    "data": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "check_number": "I-A1B2CD",
        "id_type": "drivers_licence",
        "id_type_name": "Drivers Licence",
        "check_type": "drivers_licence_dvs",
        "check_type_name": "Drivers Licence (DVS)",
        "outcome": "pass",
        "outcome_summary": "string",
        "data_summary": "string",
        "checked_at": "2024-01-01T00:00:00Z",
        "archived_at": "2024-01-01T00:00:00Z",
        "program": {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "program_name": "string"
        },
        "entity": {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "entity_number": "string",
            "entity_name": "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"
}

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