# Delete a relationship

`DELETE /relationships/{relationship_uuid}`

- Base: `DELETE https://portal.watcheye.com.au/api/v1/relationships/{relationship_uuid}`

Soft-delete a relationship by its UUID. The record is hidden from the API (it is no longer
returned by the list endpoint) but remains in the database during a recovery window. The
deleted relationship is returned in the response as confirmation.

Soft deletion is not a long-term retention mechanism: a soft-deleted relationship can be
restored within **30 days** (a portal-only action), after which it is eligible for permanent
removal and may be purged without notice. If you need to retain a relationship for audit or
compliance, do not delete it.

Any API key on your account can delete a relationship on the account. An unknown relationship
UUID returns `404`.

See the [Soft Deletion](/docs/guides/watcheye_api/soft-deletion) section of the API
guide for the full policy (recovery window, portal-only restore).

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `relationship_uuid` | path | string (uuid) | **Required.** The relationship UUID |

## Responses

### 200 Relationship deleted (soft-delete - returned as confirmation)

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object | A directed link between two entities on your account - for example a person who is a director of a company, the spouse of another person, or the beneficial owner of a trust. The two entities can belong to any program on your account. A relationship is stored once, in the direction it was created (`from_entity_uuid` -> `to_entity_uuid`). Both labels are returned so you can present the link from either entity's point of view: read `forward_label` when looking from the `from` entity and `inverse_label` when looking from the `to` entity. When `symmetric` is `true` the two labels are identical and the direction carries no extra meaning. Deleting a relationship is a soft-delete: the record is kept for audit / compliance purposes and a subsequent list call no longer returns it. |
| `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` |
| `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"
    },
    "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))