# List entities in a program

`GET /programs/{program_uuid}/entities`

- Base: `GET https://portal.watcheye.com.au/api/v1/programs/{program_uuid}/entities`

Returns the entities in the specified program. Results are paginated.

## Filters

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

- `entity_type` - one of `individual`, `business`, `vessel`, `property`
- `risk_level` - one of `low`, `medium`, `high`, or `none` for entities with no risk assigned
- `flags` - return entities that have the given flag (e.g. `pep`, `sanction`, etc.)
- `reference_number` - exact match on the customer-supplied reference number

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

## Sorting

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

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `program_uuid` | path | string (uuid) | **Required.** The program UUID Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `page` | query | integer | The page number to return Example: `1` |
| `per_page` | query | integer | The number of entities per page (defaults to 30, max 500) Example: `30` |
| `filter[entity_type]` | query | string | Only entities of the given type: `individual`, `business`, `vessel` or `property`. Enum: `individual`, `business`, `vessel`, `property` |
| `filter[risk_level]` | query | string | Use `none` to return entities with no risk assigned Enum: `low`, `medium`, `high`, `none` |
| `filter[flags]` | query | string | Return entities flagged with the given value Enum: `sanction`, `pep`, `adverse_media`, `fraud`, `hardship`, `bankruptcy`, `deceased`, `court_actions`, `deregistered`, `external_administration` |
| `filter[reference_number]` | query | string | Only the entity with the given customer reference number. Example: `CUST-12345` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at`, `entity_name`, `-entity_name` Example: `-created_at` |
| `archived` | query | boolean | Filter by archive status. * `true` - only archived entities * `false` - only non-archived entities 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 Entities list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of entities |
| `data[].uuid` | string (uuid) | The entity's UUID Example: `123e4567-e89b-12d3-a456-426614174000` |
| `data[].entity_number` | string | A short obfuscated public identifier for the entity (e.g. "E-A1-B2C-3D4") Example: `E-A1-B2C-3D4` |
| `data[].reference_number` | string or null | An optional customer-supplied reference number, unique within the program Example: `CUST-12345` |
| `data[].entity_type` | string | The type of entity: * `individual` - A natural person * `business` - A registered business * `vessel` - A vessel * `property` - A real estate property Enum: `individual`, `business`, `vessel`, `property` Example: `individual` |
| `data[].entity_name` | string or null | The display name of the entity, computed from the relevant type-specific fields Example: `Jane A Doe` |
| `data[].first_name` | string or null | First name (individuals only) Example: `Jane` |
| `data[].middle_name` | string or null | Middle name (individuals only) Example: `A` |
| `data[].last_name` | string or null | Last name (individuals only) Example: `Doe` |
| `data[].birth_date` | string (date) or null | Date of birth in `YYYY-MM-DD` format (individuals only) Example: `1980-05-15` |
| `data[].business_name` | string or null | Business name (businesses only) Example: `Acme Pty Ltd` |
| `data[].business_number` | string or null | Business identifier (businesses only); format depends on `business_number_type` Example: `12345678901` |
| `data[].business_number_type` | string or null | The type of `business_number`: * `au_abn` - Australian Business Number (11 digits) * `au_acn` - Australian Company Number (9 digits) * `uk_crn` - UK Company Registration Number (8 alphanumeric) * `other`  - Other identifier (alphanumeric, max 32 chars) Enum: `au_abn`, `au_acn`, `uk_crn`, `other` Example: `au_abn` |
| `data[].vessel_name` | string or null | Vessel name (vessels only) Example: `HMAS Sydney` |
| `data[].property_name` | string or null | Property name (properties only) Example: `1 Example Street, Sydney` |
| `data[].address_line1` | string or null | First line of address Example: `1 Example Street` |
| `data[].address_line2` | string or null | Second line of address Example: `Unit 4` |
| `data[].address_suburb` | string or null | Suburb / locality Example: `Sydney` |
| `data[].address_state` | string or null | State / region (Australian state code if `address_country` is `AU`) Example: `NSW` |
| `data[].address_postcode` | string or null | Postal / zip code Example: `2000` |
| `data[].address_country` | string or null | Two-letter ISO 3166-1 alpha-2 country code (e.g. `AU`). Either case is accepted; responses use uppercase. Example: `AU` |
| `data[].phone1` | string or null | Primary phone number Example: `+61412345678` |
| `data[].phone2` | string or null | Secondary phone number |
| `data[].phone3` | string or null | Additional phone number |
| `data[].phone4` | string or null | Additional phone number |
| `data[].email1` | string (email) or null | Primary email address Example: `jane.doe@example.com` |
| `data[].email2` | string (email) or null | Secondary email address |
| `data[].email3` | string (email) or null | Additional email address |
| `data[].email4` | string (email) or null | Additional email address |
| `data[].flags` | array of strings | Manual flags applied to the entity. Permitted values: * `sanction` - Sanctions * `pep` - Politically Exposed * `adverse_media` - Adverse Media * `fraud` - Fraud * `hardship` - Hardship * `bankruptcy` - Bankruptcy * `deceased` - Deceased * `court_actions` - Court Actions * `deregistered` - De-Registered * `external_administration` - External Administration |
| `data[].risk_level` | string or null | Risk level assigned to the entity: * `low` - Low * `medium` - Medium * `high` - High * `null` - no risk assigned (the risk has not yet been established) Enum: `low`, `medium`, `high` Example: `low` |
| `data[].archived_at` | string (date-time) or null | ISO 8601 timestamp at which the entity was archived (null if not archived) Example: `2025-04-01T10:00:00Z` |
| `data[].deleted_at` | string (date-time) or null | ISO 8601 timestamp at which the entity was soft-deleted (null if not deleted). Only populated on the response from a DELETE call. Example: `2025-04-01T10:00:00Z` |
| `data[].program_uuid` | string (uuid) | UUID of the program this entity belongs to Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].created_at` | string (date-time) | ISO 8601 timestamp at which the entity was created Example: `2025-01-01T00:00:00Z` |
| `data[].updated_at` | string (date-time) | ISO 8601 timestamp at which the entity was last updated 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) | A unique identifier for this request. This can be used to track the request in the logs and audit trail. |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "123e4567-e89b-12d3-a456-426614174000",
            "entity_number": "E-A1-B2C-3D4",
            "reference_number": "CUST-12345",
            "entity_type": "individual",
            "entity_name": "Jane A Doe",
            "first_name": "Jane",
            "middle_name": "A",
            "last_name": "Doe",
            "birth_date": "1980-05-15",
            "business_name": "Acme Pty Ltd",
            "business_number": "12345678901",
            "business_number_type": "au_abn",
            "vessel_name": "HMAS Sydney",
            "property_name": "1 Example Street, Sydney",
            "address_line1": "1 Example Street",
            "address_line2": "Unit 4",
            "address_suburb": "Sydney",
            "address_state": "NSW",
            "address_postcode": "2000",
            "address_country": "AU",
            "phone1": "+61412345678",
            "phone2": "string",
            "phone3": "string",
            "phone4": "string",
            "email1": "jane.doe@example.com",
            "email2": "user@example.com",
            "email3": "user@example.com",
            "email4": "user@example.com",
            "flags": [
                "pep",
                "adverse_media"
            ],
            "risk_level": "low",
            "archived_at": "2025-04-01T10:00:00Z",
            "deleted_at": "2025-04-01T10:00:00Z",
            "program_uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "created_at": "2025-01-01T00:00:00Z",
            "updated_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, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))