​
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

PATCH /api/v1/liquidity/utilization/util_123/settlements
Authorization: Bearer <token>
X-API-Key: <key>
Content-Type: application/json

{
  "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

GET /api/v1/liquidity/utilization/util_123

{
  "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 
{
  "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.