Our platform provides a flexible way to enrich entities with user-defined information through Metadata. This feature is available across all entities within our API, allowing you to attach custom data as key-value pairs within a metadata object.

Metadata is a powerful tool for adding relevant, user-defined information to API entities, enabling them to hold data specific to your integration needs. Metadata can be added at any time, making entities more adaptable to evolving requirements.

We encourage using metadata to enhance your API integrations, creating an experience that aligns with your application's needs.

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. This flexibility provides entities with additional context, making them adaptable to specific requirements.

In Midaz, metadata is an object that supports key-value pairs in these data types: strings (up to 100 characters), integers, floats, and booleans.

🚧

Nesting Restriction

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, allowing you to add custom data from the start. This feature helps create a detailed and complete representation of each entity in your system.

Updating and Removing Metadata

Our API follows the JSON Merge Patch RFC for metadata updates, ensuring that metadata remains adaptable and current:

• 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, the sector key will be removed, and the employee count will be updated.