WatchEye
Browse endpoints
View as Markdown OpenAPI spec

Create an entity in a program

POST /api/v1/programs/{program_uuid}/entities operationId: entity.create

Base: https://portal.watcheye.com.au/api/v1/programs/{program_uuid}/entities

Create a new entity in the specified program.

The supplied fields must be appropriate for the chosen entity_type:

  • individual - requires at least one of first_name / last_name. May supply birth_date. Business, vessel and property fields are ignored.
  • business - requires business_name. Optionally business_number + business_number_type. Individual, vessel and property fields are ignored.
  • vessel - requires vessel_name. Individual, business and property fields are ignored.
  • property - requires property_name. Address fields are optional. Individual, business and vessel fields are ignored. Phone and email fields do not apply to properties and are ignored.

The created entity record is returned in the response.

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

FieldDescription
program_uuidrequired string (uuid)

The program UUID

Header parameters

FieldDescription
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 entity details

FieldDescription
reference_number string or null

An optional customer-supplied reference number, must be unique within the program

Example: CUST-12345
entity_typerequired string

Enum: individual, business, vessel, property

Example: individual
first_name string or null

Example: Jane
middle_name string or null

Example: A
last_name string or null

Example: Doe
birth_date string (date) or null

Date of birth in YYYY-MM-DD format

Example: 1980-05-15
business_name string or null
business_number string or null
business_number_type string or null

Enum: au_abn, au_acn, uk_crn, other
vessel_name string or null
property_name string or null
address_line1 string or null
address_line2 string or null
address_suburb string or null
address_state string or null
address_postcode string or null
address_country string or null

Example: AU
phone1 string or null
phone2 string or null
phone3 string or null
phone4 string or null
email1 string (email) or null
email2 string (email) or null
email3 string (email) or null
email4 string (email) or null
flags array of strings or null

Enum: sanction, pep, adverse_media, fraud, hardship, bankruptcy, deceased, court_actions, deregistered, external_administration
risk_level string or null

An explicit null creates the entity with no risk assigned. When omitted entirely, the program's default_risk_level is applied (falling back to low).

Enum: low, medium, high

Example: low

Responses

201

Entity created

application/json
FieldDescription
data object
data.uuid string (uuid)

The entity's UUID

Example: 123e4567-e89b-12d3-a456-426614174000
data.entity_number string

A short obfuscated public identifier for the entity (e.g. "E-A1-B2C-3D4")

Example: E-A1-B2C-3D4
data.reference_number string or null

An optional customer-supplied reference number, unique within the program

Example: CUST-12345
data.entity_type string

The type of entity:

  • individual - A natural person
  • business - A registered business
  • vessel - A vessel
  • property - A real estate property

Enum: individual, business, vessel, property

Example: individual
data.entity_name string or null

The display name of the entity, computed from the relevant type-specific fields

Example: Jane A Doe
data.first_name string or null

First name (individuals only)

Example: Jane
data.middle_name string or null

Middle name (individuals only)

Example: A
data.last_name string or null

Last name (individuals only)

Example: Doe
data.birth_date string (date) or null

Date of birth in YYYY-MM-DD format (individuals only)

Example: 1980-05-15
data.business_name string or null

Business name (businesses only)

Example: Acme Pty Ltd
data.business_number string or null

Business identifier (businesses only); format depends on business_number_type

Example: 12345678901
data.business_number_type string or null

The type of business_number:

  • au_abn - Australian Business Number (11 digits)
  • au_acn - Australian Company Number (9 digits)
  • uk_crn - UK Company Registration Number (8 alphanumeric)
  • other - Other identifier (alphanumeric, max 32 chars)

Enum: au_abn, au_acn, uk_crn, other

Example: au_abn
data.vessel_name string or null

Vessel name (vessels only)

Example: HMAS Sydney
data.property_name string or null

Property name (properties only)

Example: 1 Example Street, Sydney
data.address_line1 string or null

First line of address

Example: 1 Example Street
data.address_line2 string or null

Second line of address

Example: Unit 4
data.address_suburb string or null

Suburb / locality

Example: Sydney
data.address_state string or null

State / region (Australian state code if address_country is AU)

Example: NSW
data.address_postcode string or null

Postal / zip code

Example: 2000
data.address_country string or null

Two-letter ISO 3166-1 alpha-2 country code (e.g. AU). Either case is accepted; responses use uppercase.

Example: AU
data.phone1 string or null

Primary phone number

Example: +61412345678
data.phone2 string or null

Secondary phone number
data.phone3 string or null

Additional phone number
data.phone4 string or null

Additional phone number
data.email1 string (email) or null

Primary email address

Example: jane.doe@example.com
data.email2 string (email) or null

Secondary email address
data.email3 string (email) or null

Additional email address
data.email4 string (email) or null

Additional email address
data.flags array of strings

Manual flags applied to the entity. Permitted values:

  • sanction - Sanctions
  • pep - Politically Exposed
  • adverse_media - Adverse Media
  • fraud - Fraud
  • hardship - Hardship
  • bankruptcy - Bankruptcy
  • deceased - Deceased
  • court_actions - Court Actions
  • deregistered - De-Registered
  • external_administration - External Administration
data.risk_level string or null

Risk level assigned to the entity:

  • low - Low
  • medium - Medium
  • high - High
  • null - no risk assigned (the risk has not yet been established)

Enum: low, medium, high

Example: low
data.archived_at string (date-time) or null

ISO 8601 timestamp at which the entity was archived (null if not archived)

Example: 2025-04-01T10:00:00Z
data.deleted_at string (date-time) or null

ISO 8601 timestamp at which the entity was soft-deleted (null if not deleted). Only populated on the response from a DELETE call.

Example: 2025-04-01T10:00:00Z
data.program_uuid string (uuid)

UUID of the program this entity belongs to

Example: 9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f
data.created_at string (date-time)

ISO 8601 timestamp at which the entity was created

Example: 2025-01-01T00:00:00Z
data.updated_at string (date-time)

ISO 8601 timestamp at which the entity was last updated

Example: 2025-01-01T00:00:00Z
api_reference string (uuid)
409

Conflict - a request with this Idempotency-Key is currently being processed

application/json
FieldDescription
message string

Example: A request with this Idempotency-Key is already being processed.
422

Idempotency-Key was reused with a different request body

application/json
FieldDescription
message string

Example: Idempotency-Key was reused with a different request body.
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous List entities in a program Next Show an entity