# List checks

`GET /checks`

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

Returns checks for the calling account. Results are paginated.

Each check represents a single screening run against an entity - for example a PEP and
Sanction screen, an email verification, a court records search. The list endpoint returns
a compact at-a-glance envelope per check; use the [show check](/docs/reference/check.show)
endpoint to read the typed `details` block and the uniform `results_overview` array for
a specific record.

## Group checks

A `check_type` value of `group` represents a parent record that aggregates one or more
child checks (for example a monitor run that triggers a PEP screen, an adverse media
search and a phone check on the same entity). Group checks appear in the list as
first-class records; use the `filter[parent_uuid]` filter to find their children, or
fetch the group via [show check](/docs/reference/check.show) to read the `children[]` summary.

## Filters

The following filters can be applied via the `filter[...]` query parameters:

- `check_type` - one of the operation types (e.g. `pep_sanction_check`, `phone_check`,
  `business_check`) or the special value `group` for aggregate parent records
- `outcome` - `pass` or `warning`
- `program_uuid` - only checks for entities in the given program
- `entity_uuid` - only checks for the given entity
- `parent_uuid` - only checks whose parent is the given check (use this with a group's
  uuid to list its children)
- `checked_after` - inclusive lower bound on `checked_at` (ISO 8601)
- `checked_before` - inclusive upper bound on `checked_at` (ISO 8601)

The top-level `archived` query parameter accepts `true` (only archived) or `false`
(only non-archived); omitting it returns both.

Filters that target a uuid (program, entity, parent) return an empty page when the
target uuid does not exist on the calling account, identical to the behaviour for a
uuid that does not exist at all.

## Sorting

The `sort` query parameter accepts `checked_at` (default: `-checked_at`, newest first),
`check_type` or `outcome`. Prefix with `-` for descending order.

## 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 checks per page (defaults to 30, max 500) Example: `30` |
| `filter[check_type]` | query | string | Only records of the given check type. The endpoint description lists the values. Example: `pep_sanction_check` |
| `filter[outcome]` | query | string | Only records with the given outcome. The endpoint description lists the values. Enum: `pass`, `warning` |
| `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[parent_uuid]` | query | string (uuid) | Only records whose parent is the given record. Use a group's uuid to list its children. |
| `filter[checked_after]` | query | string (date-time) | Inclusive lower bound on `checked_at` (ISO 8601). Example: `2025-01-01T00:00:00Z` |
| `filter[checked_before]` | query | string (date-time) | Inclusive upper bound on `checked_at` (ISO 8601). Example: `2025-12-31T23:59:59Z` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `checked_at`, `-checked_at`, `check_type`, `-check_type`, `outcome`, `-outcome` Example: `-checked_at` |
| `archived` | query | boolean | Filter by archive status. * `true` - only archived checks * `false` - only non-archived checks Note: The API will accept the string 'true' or the number 1 for true and the string 'false' or the number 0 for false as well as the boolean values. |

## Responses

### 200 Checks list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of checks |
| `data[].uuid` | string (uuid) | The check's UUID Example: `4d7e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].check_number` | string | A short obfuscated public identifier for the check (e.g. "C-A1B2CD") Example: `C-A1B2CD` |
| `data[].check_type` | string | The type of check that was run. One of the supported screening operations (e.g. `pep_sanction_check`, `phone_check`, `business_check`) or `group` for an aggregate record that owns one or more child checks. Example: `pep_sanction_check` |
| `data[].check_type_name` | string | Display name for the check type (e.g. "PEP and Sanction Screening", "Phone Check", "Group Check"). Suitable for showing in UIs. Example: `PEP and Sanction Screening` |
| `data[].status` | string | Lifecycle status of the check: * `pending` - the check has been created and charged but the upstream call has not started yet * `processing` - the upstream provider is being called * `complete` - the check finished successfully and `outcome` is populated * `failed` - the check could not be completed; `failed_reason` is populated and the credit charged at launch has been refunded For group checks the status is rolled up from the children: any child still pending or processing keeps the group at `processing`; the group is `failed` when any child failed, otherwise `complete` when every child is complete. Enum: `pending`, `processing`, `complete`, `failed` Example: `complete` |
| `data[].failed_reason` | string or null | Short reason why the check failed. Populated only when `status = failed`, otherwise `null`. |
| `data[].outcome` | string or null | High-level outcome of the check: * `pass` - nothing flagged * `warning` - one or more matches found that you should review `null` for group checks that have no child results yet, and for checks that have not reached `status = complete`. Enum: `pass`, `warning` Example: `warning` |
| `data[].check_summary` | string or null | Short, human-readable summary of the result (e.g. "Found 2 PEP matches", "All phones connected", "Business record exists"). `null` if the operation does not produce a summary. Example: `Found 2 PEP matches` |
| `data[].data_summary` | string or null | Short, human-readable summary of the subject the check ran against (e.g. "John A Smith, 1980-06-23" or "ACME Pty Ltd, ABN: 12 345 678 901"). `null` for group checks and for any check whose operation does not produce a subject summary. Example: `John A Smith, 1980-06-23` |
| `data[].checked_at` | string (date-time) or null | ISO 8601 timestamp at which the check was run. `null` while the check is still `pending` or `processing`. Example: `2025-01-01T00:00:00Z` |
| `data[].archived_at` | string (date-time) or null | ISO 8601 timestamp at which the check was archived (hidden from the active list in the portal). `null` when the check is not archived. |
| `data[].program` | object or null | The program the check belongs to. `null` for adhoc checks that do not belong to a program. |
| `data[].program.uuid` | string (uuid) | UUID of the program Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].program.program_name` | string | Display name of the program Example: `PEP & Sanction Daily` |
| `data[].entity` | object or null | The entity the check ran against. `null` for adhoc checks that do not target an entity record. |
| `data[].entity.uuid` | string (uuid) | UUID of the entity Example: `123e4567-e89b-12d3-a456-426614174000` |
| `data[].entity.entity_number` | string | A short obfuscated public identifier for the entity Example: `E-A1B2CD` |
| `data[].entity.entity_name` | string | Display name of the entity Example: `John A Smith` |
| `data[].parent_uuid` | string (uuid) or null | UUID of the parent (group) check this check is a child of. `null` when the check is not part of a group. |
| `data[].events_count` | integer | How many events have been raised against this check. `0` when no matches required an event. Example: `1` |
| `meta` | object |  |
| `meta.current_page` | integer | Example: `1` |
| `meta.per_page` | integer | Example: `30` |
| `meta.total` | integer | Example: `1` |
| `meta.last_page` | integer | Example: `1` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "4d7e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "check_number": "C-A1B2CD",
            "check_type": "pep_sanction_check",
            "check_type_name": "PEP and Sanction Screening",
            "status": "complete",
            "failed_reason": null,
            "outcome": "warning",
            "check_summary": "Found 2 PEP matches",
            "data_summary": "John A Smith, 1980-06-23",
            "checked_at": "2025-01-01T00:00:00Z",
            "archived_at": null,
            "program": {
                "uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
                "program_name": "PEP & Sanction Daily"
            },
            "entity": {
                "uuid": "123e4567-e89b-12d3-a456-426614174000",
                "entity_number": "E-A1B2CD",
                "entity_name": "John A Smith"
            },
            "parent_uuid": null,
            "events_count": 1
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 30,
        "total": 1,
        "last_page": 1
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

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