Metadata

Enhancing API Entities with Custom Metadata

---

Our platform provides a highly flexible way to augment entities with additional, user-defined information through a feature known as Metadata. This capability is available across all Entities within our API, enabling users to attach custom data in the form of key-value pairs within a metadata object. Whether you are creating a new entity or updating an existing one, metadata offers the ability to tailor entities to fit your unique requirements.

What is Metadata?

Metadata is a feature that lets you store extra information alongside the standard entity data model. With this feature, you can add custom attributes, annotations, or any other supplementary data that enhances the usability and relevance of the entity without changing its predefined schema. This way, you can make the entity more useful and relevant to your needs.

You can send key-value pairs using Strings (max 100 characters), Integer, Float, and Boolean.

Metadata example

For example, let's consider how an Organization entity can be represented:

{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Sanchez Tech LTDA",
    "doingBusinessAs": "The ledger.io",
    "legalDocument": "48784548000104",
    "address": {
        "line1": "Avenida Paulista, 1234",
        "line2": "CJ 203",
        "zipCode": "04696040",
        "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
}

However, if you want to enrich this Organization with additional details such as the sector and the number of employees, you could include a metadata object in your POST, PUT, or PATCH requests like so:

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

Creating Entities with Metadata

It's important to note that you can submit metadata while creating an entity using our POST endpoints. This feature enables you to add custom and relevant data to the entities right from the beginning. By doing so, you can create a more comprehensive and detailed representation of each entity in your system.

Updating and Removing Metadata

Our API ensures that metadata remains dynamic and relevant. We follow JSON Merge Patch RFC when using metadata. In general:

• Adding or updating values: Submitting a key with a new value in a PUT or PATCH request will update the existing metadata.

• Removing Keys: Omitting a previously included key in a subsequent PUT or PATCH request will result in the deletion of that key-value pair from the entity’s metadata.

Practical Example: Modifying the Metadata

If you initially created an Organization with metadata specifying the sector and the number of employees, and you wish to update the number of employees while removing the sector, you should issue a PATCH request and include the following metadata:

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

After you send the request, the sector key will be removed, and the employees count will be updated.

Conclusion

Metadata is a powerful tool for customizing API entities to carry additional, user-defined information relevant to your specific integration needs. Metadata allows entities to adapt by reflecting current and relevant information, whether added during creation or updates.

We encourage the use of metadata to enhance API integrations for a tailored experience that meets application demands.