Create a relationship on an entity

POST /api/v1/entities/{entity_uuid}/relationships operationId: relationship.create

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

Create a relationship FROM the entity in the path TO another entity on your account. The two entities can belong to different programs.

Direction is set by the order: the path entity becomes from_entity_uuid and the to_entity_uuid in the body becomes the to side. To record the relationship the other way around, send the request to the other entity instead.

A relationship of a given type is recorded once between two entities. For symmetric types (such as spouse_of) the same pair counts as one relationship regardless of direction; a repeat request returns 409.

Idempotency

This endpoint accepts the Idempotency-Key header so that retries on network failure are safe. See the Idempotency section of the API guide for the full contract.

Path parameters

Field	Description
`entity_uuid`required	string (uuid) The entity UUID (the `from` side of the relationship)

Header parameters

Field Description

Field	Description
`Idempotency-Key`	string [max 255 characters] Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the Idempotency section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f`

Idempotency-Key

string [max 255 characters]

Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the Idempotent-Replay: true response header.

Honoured on POST requests only. See the Idempotency section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The relationship details

Field	Description
`to_entity_uuid`required	string (uuid) UUID of the entity the relationship points to. Must be on your account and different from the path entity.
`relationship_type`required	string The type of relationship. Each type permits only certain entity types on the `from` and `to` sides (for example `director_of` links an individual to a business); a request that pairs incompatible entity types is rejected with a 422. Some types (such as `associated_with`) require a `comment`. 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`
`percentage_ownership`	number (float) Optional ownership percentage (0-100). Only meaningful for relationship types that support ownership (such as `shareholder_of`, `partner_in`, `owner_of`); ignored for other types. Drives ultimate beneficial owner tracing. Example: `40`
`effective_from`	string (date) Optional date the relationship is effective from (YYYY-MM-DD). Example: `2024-01-01`
`effective_to`	string (date) Optional date the relationship is effective until (YYYY-MM-DD). Must be on or after effective_from. Ignored (stored as null) for point-in-time relationship types (`buyer_of` and `seller_of`), which record a single dated event in `effective_from`. Example: `2025-01-01`
`comment`	string [max 255 characters] Free-text comment. Max 255 characters. Optional for most relationship types, but required for some (such as `associated_with`). Example: `Appointed at the 2024 AGM.`

Responses

201

Relationship created

application/json

Field	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)

409

Conflict - either a request with this Idempotency-Key is currently being processed, or a relationship of this type already exists between these entities.

application/json

Field	Description
`message`	string Example: `A relationship of this type already exists between these entities.`

422

Idempotency-Key was reused with a different request body

application/json

Field	Description
`message`	string Example: `Idempotency-Key was reused with a different request body.`

Standard error responses: 400 401 403 404 429 5XX See common error responses

Previous List an entity's relationships Next Resolve an entity's ultimate beneficial owners

Request body application/json

{
    "to_entity_uuid": "00000000-0000-0000-0000-000000000000",
    "relationship_type": "director_of",
    "percentage_ownership": 40,
    "effective_from": "2024-01-01",
    "effective_to": "2025-01-01",
    "comment": "Appointed at the 2024 AGM."
}

Response

201 Relationship created

{
    "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"
}

400 Bad Request - The request is invalid shared error response

{
    "message": "Bad Request",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "errors": {
        "data.passport_number": [
            "The passport number format is invalid."
        ]
    }
}

401 Unauthorized - the API key or account is inactive, expired, or not permitted from this IP address shared error response

{
    "message": "API Key Inactive",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

404 Not Found - The requested resource does not exist or is not accessible by this account shared error response

{
    "message": "Entity not found",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

409 Conflict - either a request with this Idempotency-Key is currently being processed, or a relationship of this type already exists between these entities.

{
    "message": "A relationship of this type already exists between these entities."
}

422 Idempotency-Key was reused with a different request body

{
    "message": "Idempotency-Key was reused with a different request body."
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}