Metadata
Metadata lets you attach your own key/value pairs to Accounts and Claims. This page covers how much you can store, how metadata changes over time and how to model it so it stays useful.
For an introduction to metadata and what the platform uses it for, see Account Claims.
How many fields can I set?
There is no limit on the number of metadata fields. The limit is on the total size of the Claim, and metadata counts towards it.
Field names count towards that total as well as the values. A Claim carrying 1,000 fields pays for 1,000 field names, even when every value is a single digit. The number of fields you set matters because it converts into size, not because there is a cap on the count.
Size limits
A Claim must stay under 200 KB in total, metadata included.
For short key/value pairs that leaves room for several thousand fields. In practice you will only approach the limit in one of two ways:
- Many fields. Around 5,000 fields with short names and short values will use the full budget.
- Large values. A single field holding a serialised document, a base64 image or a long block of text can use the whole budget on its own.
Metadata is not designed to hold documents, images or long text. Store a reference or a URL instead and keep the content in your own system.
Recommended budget
We recommend keeping metadata under 50 KB per Claim. That leaves headroom for the Claim's core fields, and for the metadata you add over time. The next section explains why that headroom matters.
Metadata accumulates
Two behaviours make a Claim's metadata grow over its life, even when every individual request is small.
Updates merge, they do not replace. When you send metadata in an update, the platform adds the keys you sent and overwrites keys that already exist. Keys you did not send stay exactly as they were. No request clears metadata by omission.
Account metadata is inherited by Claims. Metadata set on an Account is copied to the Claims created on that Account. Fields you add at the Account level count towards the size of every Claim created afterwards.
If you write metadata on a recurring basis, reuse a stable set of keys and overwrite them rather than adding a new key each time. A field named lastReviewOutcome that you overwrite stays one field. Fields named reviewOutcome_2026_01, reviewOutcome_2026_02 and so on grow without limit.
Nesting
Metadata can hold nested objects. We recommend keeping metadata flat, as a single level of key/value pairs.
The reason is how updates merge. The platform merges at the top level of the metadata map only. If a field holds an object and you update that field, the platform replaces the whole object. Any keys inside it that you did not send are lost.
Take a Claim with this metadata:
{
"meta": {
"riskProfile": {
"score": 720,
"band": "LOW",
"reviewedAt": "2026-07-01"
}
}
}
Updating only the score:
{
"meta": {
"riskProfile": {
"score": 680
}
}
}
Leaves the Claim with the score alone. band and reviewedAt are gone:
{
"meta": {
"riskProfile": {
"score": 680
}
}
}
Flat metadata avoids this. Each field merges independently, so updating one leaves the others untouched:
{
"meta": {
"riskProfileScore": 720,
"riskProfileBand": "LOW",
"riskProfileReviewedAt": "2026-07-01"
}
}
If you do need structure, keep it to two or three levels and always send the complete object when you update it.
Best practices
| Do | Why |
|---|---|
| Keep metadata flat | Each field merges independently, so partial updates are safe |
| Reuse a stable set of keys | Metadata accumulates, and new keys per event grow without limit |
| Use short, descriptive field names | Names count towards the size limit on every Claim |
| Store references to documents, not the documents | A single large value can use the whole size budget |
| Set shared context at the Account level | Account metadata is inherited by the Claims created afterwards |
| Stay under 50 KB per Claim | Leaves headroom for core fields and for metadata added later |