# Update an entity

`PATCH /entities/{entity_uuid}`

- Base: `PATCH https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}`

Update an existing entity using PATCH semantics: only the fields you supply are changed,
everything else is left as-is. Pass `null` to clear an optional field.

Notes:

* `entity_type` cannot be changed after creation. It is silently ignored if supplied.
* `birth_date` is silently ignored if the entity is locked because it has been used in an
  identification check.

## Parameters

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

## Request body

The entity fields to update. All fields are optional.

| Field | Type | Description |
|-------|------|-------------|
| `reference_number` | string or null |  |
| `first_name` | string or null |  |
| `middle_name` | string or null |  |
| `last_name` | string or null |  |
| `birth_date` | string (date) or null |  |
| `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 |  |
| `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` clears the rating to "no risk assigned" Enum: `low`, `medium`, `high` |

**Sample request**

```json
{
    "reference_number": "string",
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "birth_date": "2024-01-01",
    "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": "string",
    "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

### 200 Entity updated

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

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