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

# Metadata

> Attach custom key-value data to Midaz entities to extend the standard schema with information specific to your integration.

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.

<Warning>
  Metadata does **not** support nested values.
</Warning>

### Example of metadata

Consider an Organization entity as shown below:

<CodeGroup>
  ```jsonon JSON expandable theme={null}
  {
    "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
  }
  ```
</CodeGroup>

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:

<CodeGroup>
  ```jsonon JSON theme={null}
  {
    "metadata": {
      "sector": "Fintech",
      "employees": "50-100"
    }
  }
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```jsonon JSON theme={null}
  {
    "metadata": {
      "employees": "100-150"
    }
  }
  ```
</CodeGroup>

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