## Specification

| Attribute | Value |
| --- | --- |
| Location | Top-level request field, alongside `id`, `timestamp`, `workflow`, and `data`. |
| Type | JSON object (`object`). Arrays, strings, numbers, and booleans at the top level are rejected. |
| Required | No. Omitting the field or sending `null` is treated as absent. |
| Size limit | 200 characters total, measured across the entire serialized JSON. |
| Returned in | The synchronous response and the top level of webhook envelopes (not inside `data`). |

## Request example

JSON

```json
{
  "id": "onb-12345",
  "timestamp": "2026-06-26T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "customer_metadata": {
    "service": "checkout-api",
    "business_unit": "consumer-lending",
    "internal_ref": "order-998877"
  },
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith"
    }
  }
}
```

## Webhook example

`customer_metadata` is echoed at the top level of the webhook envelope, as a sibling of `event_id`, `event_at`, `event_type`, and `data`.

JSON

```json
{
  "event_id": "336ccd2a-b3a8-49a8-b2cc-89a4ae90feeb",
  "event_at": "2026-06-26T16:16:23.104744158Z",
  "event_type": "evaluation_completed",
  "customer_metadata": {
    "service": "checkout-api",
    "business_unit": "consumer-lending",
    "internal_ref": "order-998877"
  },
  "data": {
    "id": "onb-12345",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592"
  }
}
```

## Errors

| HTTP status | Error code | Cause |
| --- | --- | --- |
| `400` | `INVALID_REQUEST` | The value is not valid JSON, or is valid JSON but not an object. |
| `413` | `CUSTOMER_METADATA_TOO_LARGE` | The serialized object exceeds the 200-character limit.