# Create an entity in a program

`POST /programs/{program_uuid}/entities`

- Base: `POST 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](/docs/guides/watcheye_api/idempotency) section of the API guide for the full contract.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `program_uuid` | path | string (uuid) | **Required.** The program UUID |
| `Idempotency-Key` | header | 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](/docs/guides/watcheye_api/idempotency) section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f` |

## Request body

The entity details

| Field | Type | Description |
|-------|------|-------------|
| `reference_number` | string or null | An optional customer-supplied reference number, must be unique within the program Example: `CUST-12345` |
| `entity_type` | string | **Required.** 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` |

**Sample request**

```json
{
    "reference_number": "CUST-12345",
    "entity_type": "individual",
    "first_name": "Jane",
    "middle_name": "A",
    "last_name": "Doe",
    "birth_date": "1980-05-15",
    "business_name": "string",
    "business_number": "string",
    "business_number_type": "au_abn",
    "vessel_name": "string",
    "property_name": "string",
    "address_line1": "string",
    "address_line2": "string",
    "address_suburb": "string",
    "address_state": "string",
    "address_postcode": "string",
    "address_country": "AU",
    "phone1": "string",
    "phone2": "string",
    "phone3": "string",
    "phone4": "string",
    "email1": "user@example.com",
    "email2": "user@example.com",
    "email3": "user@example.com",
    "email4": "user@example.com",
    "flags": [
        "sanction"
    ],
    "risk_level": "low"
}
```

## Responses

### 201 Entity created

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `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) |  |

**Sample response**

```json
{
    "data": {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "entity_number": "E-A1-B2C-3D4",
        "reference_number": "CUST-12345",
        "entity_type": "individual",
        "entity_name": "Jane A Doe",
        "first_name": "Jane",
        "middle_name": "A",
        "last_name": "Doe",
        "birth_date": "1980-05-15",
        "business_name": "Acme Pty Ltd",
        "business_number": "12345678901",
        "business_number_type": "au_abn",
        "vessel_name": "HMAS Sydney",
        "property_name": "1 Example Street, Sydney",
        "address_line1": "1 Example Street",
        "address_line2": "Unit 4",
        "address_suburb": "Sydney",
        "address_state": "NSW",
        "address_postcode": "2000",
        "address_country": "AU",
        "phone1": "+61412345678",
        "phone2": "string",
        "phone3": "string",
        "phone4": "string",
        "email1": "jane.doe@example.com",
        "email2": "user@example.com",
        "email3": "user@example.com",
        "email4": "user@example.com",
        "flags": [
            "pep",
            "adverse_media"
        ],
        "risk_level": "low",
        "archived_at": "2025-04-01T10:00:00Z",
        "deleted_at": "2025-04-01T10:00:00Z",
        "program_uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

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

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Example: `A request with this Idempotency-Key is already being processed.` |

**Sample response**

```json
{
    "message": "A request with this Idempotency-Key is already being processed."
}
```

### 422 Idempotency-Key was reused with a different request body

Content type: `application/json`

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

**Sample response**

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

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))