# List ID checks

`GET /id-checks`

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

Returns entity-bound identification checks for the calling account. Results are paginated.

Each record represents a synchronous document verification run against a saved entity
(DVS or non-DVS). The list endpoint returns a compact envelope; use
[show ID check](/docs/reference/id-check.show) to read consent, verification details and the
typed `details` block.

ID checks run synchronously - there is no `status` field. The `outcome` is populated when
the check completes (`pass`, `fail`, or `pending` for in-flight IDPass invitations only;
IDPass is not available via this API in v1).

## Filters

- `program_uuid` - only checks for entities in the given program
- `entity_uuid` - only checks for the given entity
- `id_type` - one of the supported identification types (e.g. `drivers_licence`, `passport`)
- `check_type` - the underlying check implementation (e.g. `drivers_licence_dvs`)
- `outcome` - `pass`, `fail`, or `pending`
- `checked_after` / `checked_before` - inclusive bounds on `checked_at` (ISO 8601)

The top-level `archived` query parameter accepts `true`, `false`, or omit for both.

## Sorting

`sort` accepts `checked_at` (default `-checked_at`), `outcome`, or `id_type`.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `page` | query | integer | The page of results to return, starting at 1. Example: `1` |
| `per_page` | query | integer | The number of records per page (defaults to 30, max 500). Example: `30` |
| `archived` | query | boolean | `true` returns only archived records, `false` only non-archived records; omit it to return both. |
| `filter[program_uuid]` | query | string (uuid) | Only records for entities in the given program. |
| `filter[entity_uuid]` | query | string (uuid) | Only records for the given entity. |
| `filter[id_type]` | query | string | Only ID checks of the given document type. Example: `drivers_licence` |
| `filter[check_type]` | query | string | Only records of the given check type. The endpoint description lists the values. Example: `drivers_licence_dvs` |
| `filter[outcome]` | query | string | Only records with the given outcome. The endpoint description lists the values. Enum: `pass`, `fail`, `pending` |
| `filter[checked_after]` | query | string (date-time) | Inclusive lower bound on `checked_at` (ISO 8601). |
| `filter[checked_before]` | query | string (date-time) | Inclusive upper bound on `checked_at` (ISO 8601). |
| `sort` | query | string | The field to sort by, prefixed with `-` for descending order. The endpoint description lists the supported fields. Example: `-checked_at` |

## Responses

### 200 Paginated ID check list

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects |  |
| `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` |
| `meta` | object |  |
| `meta.current_page` | integer |  |
| `meta.per_page` | integer |  |
| `meta.total` | integer |  |
| `meta.last_page` | integer |  |
| `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"
            }
        }
    ],
    "meta": {
        "current_page": 0,
        "per_page": 0,
        "total": 0,
        "last_page": 0
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 401, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))