> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mansa.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Attach custom key–value context to requests and resources

## Overview

**Metadata** lets you attach custom key–value pairs to certain API requests and resources so you can carry business context (e.g., internal references, batch IDs, PSP transaction IDs) through your workflows. It’s echoed back in reads so you can reconcile systems without adding custom fields.

> **Not to be confused with `meta`:**\
> `meta` (inside `data.meta`) is **pagination information** (`limit`, `page`, `total`).\
> `metadata` is **your custom annotations** attached to a resource.

***

## Where you can use it

Currently supported in the **Utilization** workflow:

* **Request:** `ConfirmSettlementRequest.metadata`
* **Response:** `UtilizationItem.metadata`

Other endpoints may add `metadata` in future versions.

***

## Data format

`metadata` is a **JSON object** with string keys. Values can be any JSON type.

* **Keys:** short, stable, `snake_case` recommended (e.g., `accounting_ref`, `batch_id`).
* **Values:** string, number, boolean, `null`, arrays, or nested objects.
* **Size:** keep it small and purposeful (aim for a few KB max). Very large payloads may be rejected with `422 Unprocessable Entity`.

> Avoid PII, secrets, and volatile data. Use `metadata` for correlation, not as a primary data store.

***

## Examples

### Add metadata when confirming a settlement

```http theme={null}
PATCH /api/v2/liquidity/utilization/util_123/settlements
authorization: Bearer <token>
x-api-key: <key>
Content-Type: application/json
```

```json theme={null}
{
  "client_id": "35afa53d-43ea-47e6-8695-f4f569389a63",
  "client_request_id": "be7faa23-a157-4c19-a008-e9800b352118",
  "confirmed_use": 150000,
  "settlement_date": "2025-08-09",
  "metadata": {
    "accounting_ref": "ACC-2025-08-00987",
    "batch_id": "batch_2025_08_09_A",
    "psp_tx_id": "psp_7f2e4a",
    "notes": "FX settled via provider X"
  }
}
```

### Read metadata on a utilization item

```http theme={null}
GET /api/v2/liquidity/utilization/util_123
```

```json theme={null}
{
  "id": "util_123",
  "loan_id": "loan_abc",
  "corridor_id": "corridor_ngn",
  "intended_use": 150000,
  "confirmed_use": 150000,
  "settlement_date": "2025-08-09",
  "metadata": {
    "accounting_ref": "ACC-2025-08-00987",
    "batch_id": "batch_2025_08_09_A",
    "psp_tx_id": "psp_7f2e4a",
    "notes": "FX settled via provider X"
  },
  "created_at": "2025-08-02",
  "updated_at": "2025-08-09"
}
```

***

## Validation & errors

* Invalid shapes (e.g., non-object `metadata`) or oversized payloads may return **`422 Unprocessable Entity`** with a structured error body.
* Authentication/permission issues return **`401/403`**; rate limits return **`429`**.

**Error example**

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "metadata_invalid",
    "message": "metadata must be an object with string keys.",
    "param": "metadata",
    "doc_url": "https://docs.mansa.io/errors/metadata_invalid",
    "request_id": "req_123456789"
  }
}
```

***

## Best practices

* **Use stable keys:** choose names you can rely on long-term (`integration_order_id`, `reconciliation_run`).
* **Keep it lean:** store identifiers, not verbose blobs. Link out to your systems as needed.
* **No secrets/PII:** treat metadata as broadly visible to your team and logs.
* **Consistent casing:** prefer `snake_case` keys; avoid spaces and special characters.
* **Idempotency friendly:** include your own `client_request_id` or correlation keys in `metadata` to simplify retries and reconciliation.