Metadata

Metadata lets you enrich entities with user-defined information. It is available across all entities within our API, and you attach custom data as key-value pairs within a metadata object. You can add metadata at any time.

What is metadata?

Metadata lets you store supplementary information alongside an entity’s standard data model by adding custom attributes or annotations without altering the entity’s predefined schema. In Midaz, metadata is an object that supports key-value pairs in these data types: strings (up to 100 characters), integers, floats, and booleans.

Metadata does not support nested values.

Example of metadata

Consider an Organization entity as shown below:

{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": null,
  "legalName": "Empresa Teste Ltda",
  "doingBusinessAs": "Empresa Teste",
  "legalDocument": "86820799000188",
  "address": {
    "line1": "Rua Botucatu, 10",
    "line2": "Casa B",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "metadata": null,
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

To enrich this organization with additional information, such as industry sector and number of employees, you can include a metadata object in your POST, PUT, or PATCH requests:

{
  "metadata": {
    "sector": "Fintech",
    "employees": "50-100"
  }
}

Creating entities with metadata

When creating an entity, you can submit metadata through our POST endpoints and add custom data from the start.

Updating and removing metadata

Our API follows the JSON Merge Patch RFC for metadata updates:

Adding or Updating Values: Submitting a key with a new value in a PUT or PATCH request updates the existing metadata.
Removing Keys: Omitting a previously included key in a subsequent PUT or PATCH request removes that key-value pair from the entity’s metadata.

Practical example: modifying metadata

Suppose an Organization entity initially included metadata for sector and employee count. To update the employee count while removing the sector, send a PATCH request with the following metadata:

{
  "metadata": {
    "employees": "100-150"
  }
}

After the request is processed, the sector key will be removed, and the employee count will be updated.

Overview

Integration essentials

Stability & quality

Field dictionary

Event streaming

What is metadata?

Example of metadata

Creating entities with metadata

Updating and removing metadata

Practical example: modifying metadata

​What is metadata?

​Example of metadata

​Creating entities with metadata

​Updating and removing metadata

​Practical example: modifying metadata

What is metadata?

Example of metadata

Creating entities with metadata

Updating and removing metadata

Practical example: modifying metadata