# List an entity's relationships

`GET /entities/{entity_uuid}/relationships`

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

Returns the relationships involving the specified entity, where the entity is either the
`from` or the `to` side of the link. The related entity can be in any program on your
account. Results are paginated.

Each relationship is returned once with both `forward_label` and `inverse_label`, so you can
present it from either entity's point of view. See the
[relationship list endpoint](/docs/reference/relationship.list) for the full shape.

## Sorting

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

## 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 relationships per page (defaults to 30, max 500) Example: `30` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at`, `updated_at`, `-updated_at` Example: `-created_at` |

## Responses

### 200 Relationships list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of relationships |
| `data[].uuid` | string (uuid) | The relationship's UUID Example: `7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].relationship_type` | string | The type of relationship. Enum: `spouse_of`, `director_of`, `shareholder_of`, `trustee_of`, `beneficiary_of`, `parent_of`, `sibling_of`, `employee_of`, `officer_of`, `partner_in`, `owner_of`, `buyer_of`, `seller_of`, `associated_with` Example: `director_of` |
| `data[].forward_label` | string | Human-readable label when read from the `from` entity (e.g. "Director of"). Example: `Director of` |
| `data[].inverse_label` | string | Human-readable label when read from the `to` entity (e.g. "Has director"). Example: `Has director` |
| `data[].symmetric` | boolean | When `true` the relationship reads the same from both sides (e.g. "Spouse / de facto / domestic partner") and `forward_label` equals `inverse_label`. Example: `false` |
| `data[].from_entity_uuid` | string (uuid) | UUID of the entity the relationship is recorded from. |
| `data[].to_entity_uuid` | string (uuid) | UUID of the entity the relationship points to. |
| `data[].percentage_ownership` | number (float) or null | Ownership percentage (0-100) for relationship types that support it (such as `shareholder_of`, `partner_in` and `owner_of`). Null for other types, or when an ownership relationship's percentage is unknown. Drives ultimate beneficial owner tracing. Example: `40` |
| `data[].source` | string | How the relationship was recorded (e.g. `manual`, `workflow`, `report`, `kyb_discovery`, `import`). Example: `manual` |
| `data[].effective_from` | string (date) or null | Optional date from which the relationship is effective (YYYY-MM-DD). Example: `2024-01-01` |
| `data[].effective_to` | string (date) or null | Optional date the relationship is effective until (YYYY-MM-DD). Always null for point-in-time relationship types (`buyer_of` and `seller_of`), which record a single dated event in `effective_from`. |
| `data[].comment` | string or null | Optional free-text comment describing the relationship. Example: `Appointed at the 2024 AGM.` |
| `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": "7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "relationship_type": "director_of",
            "forward_label": "Director of",
            "inverse_label": "Has director",
            "symmetric": false,
            "from_entity_uuid": "00000000-0000-0000-0000-000000000000",
            "to_entity_uuid": "00000000-0000-0000-0000-000000000000",
            "percentage_ownership": 40,
            "source": "manual",
            "effective_from": "2024-01-01",
            "effective_to": null,
            "comment": "Appointed at the 2024 AGM.",
            "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))