> ## 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 metadata to Midaz entities so you can extend the standard ledger schema with data specific to your integration and business needs.

**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.

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

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