# Archive an entity

`POST /entities/{entity_uuid}/archive`

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

Archives the entity together with all checks, reports, events, notes and identification
checks belonging to it. Archived records remain fully visible via list and show endpoints
and can be included or excluded with the `archived` query parameter on the entities list.

Use archive instead of delete when you need to take a record out of day-to-day workflows
but want to keep it accessible for compliance, audit or historical reporting. See the
[Soft Deletion](/docs/guides/watcheye_api/soft-deletion#prefer-archiving-over-deletion-for-compliance)
section of the API guide for the differences between archive and delete.

Calling archive on an entity that is already archived returns the entity in its current
state without recording a new audit entry or re-cascading to the child records.

The response body contains the entity with `archived_at` set to the ISO 8601 timestamp at
which the archive took effect. (The `archived_at` field is always present on entity
responses; it is `null` when the entity is not archived and an ISO 8601 timestamp when
it is.)

## 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 |
|------|----|------|-------------|
| `entity_uuid` | path | string (uuid) | **Required.** The entity 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` |

## Responses

### 200 Entity archived

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, 403, 404, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))