Entities

Alpha

The light entity surface: create, fetch, update, and archive records, then screen them on demand.

Base path: /v1

Purpose

Entities are the first-class resource in Customer Intelligence. An entity represents a person, business, or wallet you're onboarding. Registration is cheap and idempotent. No screening happens until you call `/check`.

Usage

Register at the start of your flow with whatever identifiers you have. Look up by your `reference_id` when you only store your own id. PATCH to update display name or metadata. Archive when a user closes their account.

Common Workflow

1`POST /entities`: create or enrich idempotently on `reference_id`.
2`GET /entities?reference_id=`: resolve your id to our entity.
3`GET /entities/{entity_id}`: fetch by Falador id with active identifiers.
4`PATCH /entities/{entity_id}`: update `display_name` and/or `metadata`.
5`DELETE /entities/{entity_id}`: soft-delete (`status: archived`).

Integration Notes

First call with a `reference_id` creates; later calls with the same id return the same entity and attach new identifiers.
`POST /entities` requires `Idempotency-Key` header (UUID).
Screening name is stored as `display_name`, which drives sanctions matching.

API Reference

POST/v1/entities

Register Entity

Create or enrich an entity idempotently.

The front door. First call with a `reference_id` creates the entity; later calls with the same `reference_id` return the same entity and enrich it with any new identifiers. Requires `Idempotency-Key` header.

Parameters

Name	Type	Required	Description
`Idempotency-Key`	string (header)	Required	UUID per registration attempt. Same key + same body replays; different body → `409`.e.g. 550e8400-e29b-41d4-a716-446655440000
`entity_type`	string	Required	`individual`, `business`, or `wallet`.e.g. individual
`reference_id`	string	Required	Your stable id for this user, used as the idempotency anchor.e.g. user_8412
`name`	string	Optional	Screening name; stored as `display_name`.e.g. Jane Smith
`identifiers`	object	Optional	`{id_type: [values]}`, e.g. `{"email":["a@b.com"],"device_id":["dvc_1"]}`.e.g. {"email":["jane@mailinator.com"],"phone":["+14155552671"],"device_id":["dvc_abc123"]}
`metadata`	object	Optional	Free-form JSON stored on the entity.e.g. {"signup_source":"web"}

Request body

Schema

{
  "entity_type": "individual",
  "reference_id": "user_8412",
  "name": "Jane Smith",
  "identifiers": {
    "email": [
      "jane@mailinator.com"
    ],
    "phone": [
      "+14155552671"
    ],
    "device_id": [
      "dvc_abc123"
    ]
  }
}

Examples

Sample input

{
  "headers": {
    "Authorization": "Bearer $TOKEN",
    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000"
  },
  "body": {
    "entity_type": "individual",
    "reference_id": "user_8412",
    "name": "Jane Smith",
    "identifiers": {
      "email": [
        "jane@mailinator.com"
      ],
      "phone": [
        "+14155552671"
      ],
      "device_id": [
        "dvc_abc123"
      ]
    }
  }
}

Sample output

{
  "request_id": "req_a1b2c3",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "entity_type": "individual",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active",
    "created_at": "2026-07-01T08:00:00Z",
    "updated_at": "2026-07-01T08:00:00Z"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id": "id_01",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    }
  ]
}

LLM markdown preview

### Register Entity

Create or enrich an entity idempotently.

Use `POST /v1/entities` to create or enrich an entity idempotently.

The front door. First call with a `reference_id` creates the entity; later calls with the same `reference_id` return the same entity and enrich it with any new identifiers. Requires `Idempotency-Key` header.

Required parameters:
- `Idempotency-Key`: string (header) (example: `"550e8400-e29b-41d4-a716-446655440000"`). UUID per registration attempt. Same key + same body replays; different body → `409`.
- `entity_type`: string (example: `"individual"`). `individual`, `business`, or `wallet`.
- `reference_id`: string (example: `"user_8412"`). Your stable id for this user, used as the idempotency anchor.

Optional parameters:
- `name`: string (example: `"Jane Smith"`). Screening name; stored as `display_name`.
- `identifiers`: object (example: `{"email":["jane@mailinator.com"],"phone":["+14155552671"],"device_id":["dvc_abc123"]}`). `{id_type: [values]}`, e.g. `{"email":["a@b.com"],"device_id":["dvc_1"]}`.
- `metadata`: object (example: `{"signup_source":"web"}`). Free-form JSON stored on the entity.

Example request:

```json
{
  "headers": {
    "Authorization": "Bearer $TOKEN",
    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000"
  },
  "body": {
    "entity_type": "individual",
    "reference_id": "user_8412",
    "name": "Jane Smith",
    "identifiers": {
      "email": [
        "jane@mailinator.com"
      ],
      "phone": [
        "+14155552671"
      ],
      "device_id": [
        "dvc_abc123"
      ]
    }
  }
}
```

Example response:

```json
{
  "request_id": "req_a1b2c3",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "entity_type": "individual",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active",
    "created_at": "2026-07-01T08:00:00Z",
    "updated_at": "2026-07-01T08:00:00Z"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id": "id_01",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    }
  ]
}
```

GET/v1/entities

Lookup by Reference ID

Resolve your reference_id to an entity.

Look up an entity using your own `reference_id`. Returns the entity and its active identifiers. Useful when you only persisted your id on your side.

Parameters

Name	Type	Required	Description
`reference_id`	string (query)	Required	Your stable id for the entity.e.g. user_8412

Examples

Sample input

{
  "query": {
    "reference_id": "user_8412"
  }
}

Sample output

{
  "request_id": "req_b2c3d4",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    }
  ]
}

LLM markdown preview

### Lookup by Reference ID

Resolve your reference_id to an entity.

Use `GET /v1/entities` to resolve your reference_id to an entity.

Look up an entity using your own `reference_id`. Returns the entity and its active identifiers. Useful when you only persisted your id on your side.

Required parameters:
- `reference_id`: string (query) (example: `"user_8412"`). Your stable id for the entity.

Example request:

```json
{
  "query": {
    "reference_id": "user_8412"
  }
}
```

Example response:

```json
{
  "request_id": "req_b2c3d4",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    }
  ]
}
```

GET/v1/entities/{entity_id}

Get Entity

Fetch an entity by Falador id.

Returns the entity and all active identifiers attached to it.

Parameters

Name	Type	Required	Description
`entity_id`	string	Required	Falador entity UUID.e.g. 9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e

Examples

Sample input

{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  }
}

Sample output

{
  "request_id": "req_c3d4e5",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "entity_type": "individual",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active",
    "metadata": {
      "signup_source": "web"
    },
    "created_at": "2026-07-01T08:00:00Z",
    "updated_at": "2026-07-01T09:15:00Z"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    },
    {
      "object": "identifier",
      "id_type": "device_id",
      "value_raw": "dvc_abc123",
      "status": "active"
    }
  ]
}

LLM markdown preview

### Get Entity

Fetch an entity by Falador id.

Use `GET /v1/entities/{entity_id}` to fetch an entity by falador id.

Returns the entity and all active identifiers attached to it.

Required parameters:
- `entity_id`: string (example: `"9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"`). Falador entity UUID.

Example request:

```json
{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  }
}
```

Example response:

```json
{
  "request_id": "req_c3d4e5",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "entity_type": "individual",
    "reference_id": "user_8412",
    "display_name": "Jane Smith",
    "status": "active",
    "metadata": {
      "signup_source": "web"
    },
    "created_at": "2026-07-01T08:00:00Z",
    "updated_at": "2026-07-01T09:15:00Z"
  },
  "identifiers": [
    {
      "object": "identifier",
      "id_type": "email",
      "value_raw": "jane@mailinator.com",
      "status": "active"
    },
    {
      "object": "identifier",
      "id_type": "device_id",
      "value_raw": "dvc_abc123",
      "status": "active"
    }
  ]
}
```

PATCH/v1/entities/{entity_id}

Update Entity

Update display name or metadata.

Partial update: only fields present in the body are applied. Omitted fields are untouched; explicit `null` clears `display_name`. Change the name and the next `/check` screens the new one.

Parameters

Name	Type	Required	Description
`entity_id`	string	Required	Falador entity UUID.e.g. 9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e
`display_name`	string	Optional	Updated screening / display name.e.g. Jane A. Smith
`metadata`	object	Optional	Shallow-merged into existing metadata.e.g. {"tier":"pro"}

Request body

Schema

{
  "display_name": "Jane A. Smith",
  "metadata": {
    "tier": "pro"
  }
}

Examples

Sample input

{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  },
  "body": {
    "display_name": "Jane A. Smith",
    "metadata": {
      "tier": "pro"
    }
  }
}

Sample output

{
  "request_id": "req_d4e5f6",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "display_name": "Jane A. Smith",
    "metadata": {
      "signup_source": "web",
      "tier": "pro"
    },
    "updated_at": "2026-07-01T10:30:00Z"
  }
}

LLM markdown preview

### Update Entity

Update display name or metadata.

Use `PATCH /v1/entities/{entity_id}` to update display name or metadata.

Partial update: only fields present in the body are applied. Omitted fields are untouched; explicit `null` clears `display_name`. Change the name and the next `/check` screens the new one.

Required parameters:
- `entity_id`: string (example: `"9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"`). Falador entity UUID.

Optional parameters:
- `display_name`: string (example: `"Jane A. Smith"`). Updated screening / display name.
- `metadata`: object (example: `{"tier":"pro"}`). Shallow-merged into existing metadata.

Example request:

```json
{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  },
  "body": {
    "display_name": "Jane A. Smith",
    "metadata": {
      "tier": "pro"
    }
  }
}
```

Example response:

```json
{
  "request_id": "req_d4e5f6",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "display_name": "Jane A. Smith",
    "metadata": {
      "signup_source": "web",
      "tier": "pro"
    },
    "updated_at": "2026-07-01T10:30:00Z"
  }
}
```

DELETE/v1/entities/{entity_id}

Archive Entity

Soft-delete an entity.

Sets `status: archived`. The row is kept for audit and is recoverable. Idempotent: archiving an already-archived entity succeeds.

Parameters

Name	Type	Required	Description
`entity_id`	string	Required	Falador entity UUID to archive.e.g. 9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e

Examples

Sample input

{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  }
}

Sample output

{
  "request_id": "req_e5f6g7",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "status": "archived",
    "updated_at": "2026-07-03T14:00:00Z"
  }
}

LLM markdown preview

### Archive Entity

Soft-delete an entity.

Use `DELETE /v1/entities/{entity_id}` to soft-delete an entity.

Sets `status: archived`. The row is kept for audit and is recoverable. Idempotent: archiving an already-archived entity succeeds.

Required parameters:
- `entity_id`: string (example: `"9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"`). Falador entity UUID to archive.

Example request:

```json
{
  "path": {
    "entity_id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e"
  }
}
```

Example response:

```json
{
  "request_id": "req_e5f6g7",
  "entity": {
    "object": "entity",
    "id": "9b2d7f1a-4c8e-4a1b-9f3d-2e8c1a5b6d7e",
    "status": "archived",
    "updated_at": "2026-07-03T14:00:00Z"
  }
}
```