Create a relationship on an entity
/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.
Example Request
POSTRequest Schema
entity_uuid
The entity UUID (the `from` side of the relationship)
Idempotency-Key
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
to_entity_uuid
UUID of the entity the relationship points to. Must be on your account and different from the path entity.
relationship_type
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`.
percentage_ownership
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.
effective_from
Optional date the relationship is effective from (YYYY-MM-DD).
effective_to
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`.
comment
Free-text comment. Max 255 characters. Optional for most relationship types, but required for some (such as `associated_with`).
Available Response Data
13 Data Pointsuuid uuid
The relationship's UUID
relationship_type enum
The type of relationship: spouse_of, director_of, shareholder_of, trustee_of, beneficiary_of, parent_of, …
forward_label string (Human-readable label when read from the from entity (e.g. "Director of"))
inverse_label string (Human-readable label when read from the to entity (e.g. "Has director"))
symmetric boolean
When true the relationship reads the same from both sides
from_entity_uuid uuid
UUID of the entity the relationship is recorded from
to_entity_uuid uuid
UUID of the entity the relationship points to
percentage_ownership number (Ownership percentage (0-100) for relationship types that support it (such as shareholder_of, partner_in and owner_of))
source string (How the relationship was recorded (e.g. manual, workflow, report, kyb_discovery, import))
effective_from string (Optional date from which the relationship is effective (YYYY-MM-DD))
effective_to string (Optional date the relationship is effective until (YYYY-MM-DD))
comment string
Optional free-text comment describing the relationship
api_reference uuid
unique request identifier for log tracing and audit
API Data Scale & Coverage tag
Unmatched data depth to power your compliance and verification workflows.
Sandbox Environment
Build and test against a sandbox account. Sandbox is a separate account with its own UUID and its own API keys, and the environment is fixed at the account level, so you cannot switch an existing key between live and sandbox with a parameter or header. Both share the same base URL, so the account behind your key is what determines which environment you are in. GET /v1/account returns an environment field of live or sandbox, and that is the authoritative answer.
Calls on a sandbox key are not billed. Every endpoint, response shape, error envelope, idempotency and rate-limit behaviour mirrors live, so the only change when you move to production should be the credentials. Sandbox accounts are provisioned by your Global Data account manager.
Technical Use Cases tag
Onboarding straight from your system
Create the relationship as part of your own onboarding flow, so WatchEye is populated at the moment the customer is captured instead of by a later import.
Bulk migration
Load an existing book into WatchEye programmatically. Spread the calls evenly instead of bursting, and send an Idempotency-Key so a retried request cannot create a duplicate.
Keeping two systems in step
Mirror creations from your CRM or core system so the monitored population matches the customers you hold.
Compliance & Security tag
Enterprise-grade infrastructure audited against the standards your regulators require.
Common Questions tag
Everything you need to know about implementation details and compliance infrastructure.
rocket_launch Implementation
Is it safe to retry this call?
add
Is it safe to retry this call?
Yes, if you send an Idempotency-Key header. A connection can drop after WatchEye has processed a request but before the response reaches you, and a blind retry would risk a duplicate record or a double charge.
The key is any string of your choosing up to 255 characters, unique per logical operation, and a fresh UUID per request is the usual approach. Sending the same key again returns the original response byte for byte, with no new database changes and no new billable charge.
The header is honoured on POST only. It is silently ignored on GET, PATCH and DELETE, which are already idempotent at the HTTP level.
rocket_launch Implementation
What are the rate limits?
add
What are the rate limits?
600 requests per minute by default, enforced with a 60-second fixed window. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
Exceeding the limit returns 429 Too Many Requests with a Retry-After header giving the number of seconds to wait, and X-RateLimit-Reset giving the reset timestamp. Schedule retries from Retry-After instead of a fixed sleep, and slow down before you hit zero, not after.
Higher limits can be arranged case by case through WatchEye support.
Ready to integrate Create a relationship on an entity?
Talk to our team about credentials, sandbox access and the right combination of endpoints for your workflow.