# Launch an adhoc ID check

`POST /adhoc-id-checks`

- Base: `POST 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](/docs/reference/id-check.launch) for consent, idempotency
and billing behaviour.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `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 |
|-------|------|-------------|
| `id_type` | string | **Required.** Identification type to run. See SELECTABLE_ID_TYPES in the portal field reference. Example: `drivers_licence` |
| `consent_obtained` | boolean | **Required.** 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](/docs/guides/watcheye_api/id-checks#consent) section of the API guide for your full obligations and an illustrative starting point for the wording. |
| `data` | object | **Required.** 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` |

**Sample request**

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

## Responses

### 200 Adhoc ID check completed

Content type: `application/json`

| Field | Type | 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](/docs/guides/watcheye_api/idpass#lifecycle-and-status) 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 | One of: object 1; object 2; object 3; object 4; object 5; object 6. |
| `data.details (object 1).verification_result_code` | string | Enum: `Y`, `N`, `D` |
| `data.details (object 1).originating_agency_code` | string or null |  |
| `data.details (object 1).verification_request_number` | string or null |  |
| `data.details (object 1).additional_information` | array of strings |  |
| `data.details (object 2).api_reference` | string or null |  |
| `data.details (object 2).message` | string or null |  |
| `data.details (object 2).match_results` | object or null |  |
| `data.details (object 2).match_results.first_name` | string |  |
| `data.details (object 2).match_results.last_name` | string |  |
| `data.details (object 2).match_results.dob` | string | Date of birth match result from the upstream provider. |
| `data.details (object 3).api_reference` | string or null |  |
| `data.details (object 3).person_match` | string or null |  |
| `data.details (object 4).api_reference` | string or null |  |
| `data.details (object 4).reporting_reference` | string or null | Unique transaction identifier from the data source. |
| `data.details (object 4).match_status` | string or null | Overall match result. `Match` indicates the supplied identity was fully verified. Enum: `Match`, `NoMatch` |
| `data.details (object 4).document_verified` | boolean | Whether NZTA reports the supplied licence details as verified. |
| `data.details (object 4).additional_information` | string or null | Explanatory message returned by the data source, typically alongside a `NoMatch` result. |
| `data.details (object 5).api_reference` | string or null |  |
| `data.details (object 5).reporting_reference` | string or null | Unique transaction identifier from the data source. |
| `data.details (object 5).match_status` | string or null | Overall match result. `Match` indicates the supplied identity was fully verified. Enum: `Match`, `NoMatch` |
| `data.details (object 5).document_verified` | boolean | Whether the NZ Department of Internal Affairs (DIA) reports the supplied passport details as verified. |
| `data.details (object 5).additional_information` | string or null | Explanatory message returned by the data source, typically alongside a `NoMatch` result. |
| `data.details (object 6).api_reference` | string or null |  |
| `data.details (object 6).payroll_person` | string or null |  |
| `data.details (object 6).super_person` | string or null |  |
| `api_reference` | string (uuid) |  |

**Sample response**

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

### 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, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))