# Launch an ID check against an entity

`POST /entities/{entity_uuid}/id-checks`

- Base: `POST 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](/docs/guides/watcheye_api/id-checks#consent) section of the API
guide for your full obligations and an illustrative starting point.

## 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 |
|-------|------|-------------|
| `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 ID check completed - full detail payload returned inline

Content type: `application/json`

| Field | Type | 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](/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": "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"
}
```

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