# List adhoc checks

`GET /adhoc-checks`

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

Returns adhoc ("quick") checks for the calling account. Results are paginated.

An adhoc check is a one-off screening run performed from the portal by an account user
against a free-form subject - they do not belong to a program or entity record. They
use the same underlying screening operations as entity checks (PEP and Sanction, phone,
business, etc.) so the typed `details` payload uses the same per-operation schemas.

The list endpoint returns a compact at-a-glance envelope per check; use the
[show adhoc check](/docs/reference/adhoc-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 adhoc checks (for example a quick check that runs a PEP screen and a phone check
on the same subject in one go). 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 adhoc check](/docs/reference/adhoc-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`
- `created_by` - `user` (only checks launched by a portal user) or `api_key` (only checks
  launched by any API key on this account)
- `created_by_user_uuid` - only adhoc checks launched by the given portal user
- `created_by_api_key_uuid` - only adhoc checks launched by the given API key
- `parent_uuid` - only adhoc 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)

Filters that target a uuid (user, api key, 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.

[Soft-deleted](/docs/guides/watcheye_api/soft-deletion) adhoc checks are excluded.

Adhoc checks do not support archiving - there is no `archived` query parameter and no
`archived_at` field on the response.

## 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 adhoc 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[created_by]` | query | string | Only records created by the given kind of actor: `user` (a portal user) or `api_key`. Enum: `user`, `api_key` |
| `filter[created_by_user_uuid]` | query | string (uuid) | Only records created by the given portal user. |
| `filter[created_by_api_key_uuid]` | query | string (uuid) | Only records created by the given API key. |
| `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` |

## Responses

### 200 Adhoc checks list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of adhoc checks |
| `data[].uuid` | string (uuid) | The adhoc check's UUID Example: `6f9e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].check_number` | string | A short obfuscated public identifier for the adhoc check (e.g. "Q-A1B2CD") Example: `Q-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 adhoc 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 adhoc 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 did 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"). For adhoc checks the value is captured at run time from the data the user typed into the quick-check form. `null` for group checks and for checks whose operation did 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[].created_by` | object or null | Identifies who launched the adhoc check. The `type` discriminator picks the shape of the remaining fields: * `{ type: "user", uuid, username }` - a portal user launched the adhoc check. * `{ type: "api_key", uuid, label }` - an API key on this account launched the adhoc check. * `null` - rare legacy rows from before actor attribution was recorded. If the user has since been deleted from the account the historical record is retained and the original `user` discriminator is still returned. |
| `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[].parent_uuid` | string (uuid) or null | UUID of the parent (group) adhoc check this check is a child of. `null` when the check is not part of a group. |
| `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": "6f9e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "check_number": "Q-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",
            "created_by": {
                "type": "user",
                "uuid": "00000000-0000-0000-0000-000000000000",
                "username": "string",
                "label": "string"
            },
            "parent_uuid": null
        }
    ],
    "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))