# List events

`GET /events`

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

Returns events for the calling account. Results are paginated.

Each event represents a "thing your team should look at" produced by a screening check -
typically a positive PEP/sanction match, a phone or email match, an adverse media hit,
etc. Events have lifecycle status (`new` -> `investigating` -> `closed_*`) that you can
transition via the [PATCH event](/docs/reference/event.update) endpoint.

Events do not get deleted on their own; closing them sets their `status` to one of the
`closed_*` values.

## Filters

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

- `status` - one of `new`, `investigating`, `closed_dismissed`, `closed_duplicate`, `closed_error`, `closed_confirmed`
- `check_type` - one of the operation types (e.g. `pep_sanction_check`, `phone_check`, `business_check`)
- `entity_uuid` - only events for the given entity
- `program_uuid` - only events for entities in the given program
- `check_uuid` - only events from the given check
- `created_at_from` - inclusive lower bound on event creation time (ISO 8601)
- `created_at_to` - inclusive upper bound on event creation time (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 (entity, program, check) 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 `created_at` (default: `-created_at`, newest first)
or `status`. 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 events per page (defaults to 30, max 500) Example: `30` |
| `filter[status]` | query | string | Only records with the given status. The endpoint description lists the values. Enum: `new`, `investigating`, `closed_dismissed`, `closed_duplicate`, `closed_error`, `closed_confirmed` |
| `filter[check_type]` | query | string | Only records of the given check type. The endpoint description lists the values. Example: `pep_sanction_check` |
| `filter[entity_uuid]` | query | string (uuid) | Only records for the given entity. |
| `filter[program_uuid]` | query | string (uuid) | Only records for entities in the given program. |
| `filter[check_uuid]` | query | string (uuid) | Only events raised by the given check. |
| `filter[created_at_from]` | query | string (date-time) | Inclusive lower bound on `created_at` (ISO 8601). Example: `2025-01-01T00:00:00Z` |
| `filter[created_at_to]` | query | string (date-time) | Inclusive upper bound on `created_at` (ISO 8601). Example: `2025-12-31T23:59:59Z` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at`, `status`, `-status` Example: `-created_at` |
| `archived` | query | boolean | Filter by archive status. * `true` - only archived events * `false` - only non-archived events 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 Events list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of events |
| `data[].uuid` | string (uuid) | The event's UUID Example: `4d7e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].event_number` | string | A short obfuscated public identifier for the event (e.g. "V-A1-B2C-3D4") Example: `V-A1-B2C-3D4` |
| `data[].status` | string | Lifecycle status of the event: * `new` - the event has just been raised and not yet triaged * `investigating` - someone is actively working the event * `closed_dismissed` - reviewed and dismissed (e.g. false positive) * `closed_duplicate` - duplicates another event * `closed_error` - caused by a data entry error * `closed_confirmed` - confirmed and acted on Enum: `new`, `investigating`, `closed_dismissed`, `closed_duplicate`, `closed_error`, `closed_confirmed` Example: `new` |
| `data[].check_type` | string | The operation type of the check that produced this event (e.g. `pep_sanction_check`, `phone_check`, `business_check`). Example: `pep_sanction_check` |
| `data[].check_summary` | string or null | Short, human-readable summary of the parent check (denormalised from the linked check so that listing events does not require an N+1 fetch into checks). Example: `Searched for "Jane Doe" in PEP and Sanction lists for AU, NZ, US, GB, CA.` |
| `data[].check_response_index` | integer or null | For `separate` event grouping, the zero-based index into the parent check's `response` array that this event represents. `null` for `grouped` events that aggregate every match for the entity into a single event. Example: `0` |
| `data[].check_result_ids` | array of integers | Provider-side result identifiers that triggered this event. Combined with the parent check's `response`, this lets integrators pull the underlying match data for the event. |
| `data[].archived_at` | string (date-time) or null | ISO 8601 timestamp at which the event was archived (null if not archived) |
| `data[].deleted_at` | string (date-time) or null | ISO 8601 timestamp at which the event was soft-deleted (null if not deleted) |
| `data[].entity_uuid` | string (uuid) | UUID of the entity this event was raised against Example: `123e4567-e89b-12d3-a456-426614174000` |
| `data[].program_uuid` | string (uuid) | UUID of the program the entity belongs to Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].check_uuid` | string (uuid) | UUID of the check that produced this event Example: `0a1b2c3d-4e5f-6789-abcd-ef0123456789` |
| `data[].notes_count` | integer | How many notes (system + user) are attached to the event. Only the count is included on the list endpoint; the detail endpoint additionally embeds the notes themselves. Example: `0` |
| `data[].created_at` | string (date-time) | ISO 8601 timestamp at which the event was created Example: `2025-01-01T00:00:00Z` |
| `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",
            "event_number": "V-A1-B2C-3D4",
            "status": "new",
            "check_type": "pep_sanction_check",
            "check_summary": "Searched for \"Jane Doe\" in PEP and Sanction lists for AU, NZ, US, GB, CA.",
            "check_response_index": 0,
            "check_result_ids": [
                12345,
                12346
            ],
            "archived_at": null,
            "deleted_at": null,
            "entity_uuid": "123e4567-e89b-12d3-a456-426614174000",
            "program_uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "check_uuid": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
            "notes_count": 0,
            "created_at": "2025-01-01T00:00:00Z"
        }
    ],
    "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))