# List the attachments on an entity

`GET /entities/{entity_uuid}/attachments`

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

Returns the attachments on the specified entity. Results are paginated and accept the
same filters, sorting and `archived` parameter as
[GET /v1/attachments](/docs/reference/attachment.list).

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `entity_uuid` | path | string (uuid) | **Required.** The entity UUID |
| `page` | query | integer | The page of results to return, starting at 1. Example: `1` |
| `per_page` | query | integer | The number of attachments per page (defaults to 30, max 500) Example: `30` |
| `filter[category]` | query | string | Only attachments with exactly this category. Example: `Trust Deed` |
| `filter[filename]` | query | string | Only attachments whose name contains this text (not case sensitive). Example: `deed` |
| `filter[mime_type]` | query | string | Only attachments of this type. Example: `application/pdf` |
| `filter[created_by]` | query | string | Only attachments uploaded by any portal user (`user`) or any API key (`api_key`) on this account. Enum: `user`, `api_key` |
| `filter[created_by_user_uuid]` | query | string (uuid) | Only attachments uploaded by a specific portal user. |
| `filter[created_by_api_key_uuid]` | query | string (uuid) | Only attachments uploaded by a specific API key. |
| `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`, `filename`, `-filename`, `size_bytes`, `-size_bytes` Example: `-created_at` |
| `archived` | query | boolean | Filter by archive status. * `true` - only archived attachments * `false` - only non-archived attachments 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 Attachments list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of attachments |
| `data[].uuid` | string (uuid) | The attachment's UUID Example: `3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d` |
| `data[].attachment_number` | string | A short public identifier for the attachment, shown in the portal Example: `EA-3C-9A1-0B7` |
| `data[].entity_uuid` | string (uuid) | UUID of the entity the attachment is on |
| `data[].program_uuid` | string (uuid) | UUID of the program the entity belongs to |
| `data[].filename` | string | The name of the file as uploaded Example: `Smith Family Trust Deed.pdf` |
| `data[].category` | string | What the file is. Any text up to 100 characters; `Other` when none is given. A category that matches an existing one on the account (ignoring case and extra spaces) is stored with the existing spelling, so `trust deed` is stored as `Trust Deed`. The categories offered in the portal are: Trust Deed, Company Constitution, Partnership Agreement, ASIC Extract, Companies House Extract, Identity Document, Proof of Address, Statutory Declaration, Declaration, Contract / Agreement, Correspondence, Financial Statement and Other. Example: `Trust Deed` |
| `data[].description` | string or null | An optional description of the file (max 2000 characters) Example: `Signed copy received from the trustee` |
| `data[].mime_type` | string | The type of the file, detected from its contents Example: `application/pdf` |
| `data[].format` | string | A readable name for the type of file Enum: `PDF`, `Image`, `Word`, `Excel`, `CSV`, `Text`, `RTF`, `Email`, `Other` Example: `PDF` |
| `data[].size_bytes` | integer | The size of the file in bytes Example: `248113` |
| `data[].sha256` | string | SHA-256 hash of the file contents, as lowercase hex. Files with the same hash have identical contents. Example: `9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08` |
| `data[].created_by` | object or null | Identifies who uploaded the file. The `type` discriminator picks the shape of the remaining fields: * `{ type: "user", uuid, username }` - a portal user uploaded the file. * `{ type: "api_key", uuid, label }` - an API key on this account uploaded the file. * `null` - the user or API key that uploaded the file is no longer available. |
| `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 uploaded the file. |
| `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[].archived_at` | string (date-time) or null | ISO 8601 timestamp at which the attachment was archived with its entity (null if not archived) |
| `data[].created_at` | string (date-time) | Example: `2025-01-01T00:00:00Z` |
| `data[].updated_at` | string (date-time) | 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": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
            "attachment_number": "EA-3C-9A1-0B7",
            "entity_uuid": "00000000-0000-0000-0000-000000000000",
            "program_uuid": "00000000-0000-0000-0000-000000000000",
            "filename": "Smith Family Trust Deed.pdf",
            "category": "Trust Deed",
            "description": "Signed copy received from the trustee",
            "mime_type": "application/pdf",
            "format": "PDF",
            "size_bytes": 248113,
            "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "created_by": {
                "type": "user",
                "uuid": "00000000-0000-0000-0000-000000000000",
                "username": "string",
                "label": "string"
            },
            "archived_at": "2024-01-01T00:00:00Z",
            "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, 403, 404, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))