Metadata

Overview

Entity, Counterpart, and Payable objects can have arbitrary metadata associated with them. Monite API Partners can use metadata to store additional structured information about these objects, such as the object IDs from other systems.

Metadata is not part of the objects themselves. Instead, it is accessed via the /partner_metadata subresource of the corresponding resources:

/entities/{entity_id}/partner_metadata

/counterparts/{counterpart_id}/partner_metadata

/payables/{payable_id}/partner_metadata

Use the HTTP PUT method to set the metadata, and GET to read it.

Metadata format

The <resource>/partner_metadata accept and return the metadata in the following format, where metadata can be an arbitrary JSON object up to 2000 bytes in size:

{
  "metadata": {

    // Metadata goes here
    "custom_field_1": "value",
    "custom_field_2": 42,
    "custom_field_3": true,
    ...

  }
}

Manage metadata

Set metadata

Use PUT <resource>/partner_metadata to add metadata or replace existing metadata. For example:

curl -X PUT 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'

A 200 OK response means the metadata was successfully saved. If the metadata exceeds the 2 KB limit, a 422 response is returned.

Get metadata

Use GET <resource>/partner_metadata to get existing metadata. For example:

curl 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: ACCESS_TOKEN'

If there is no metadata associated with the specified resource, the metadata field in the response is an empty object {}.

Partially update metadata

If you need to add, modify, or delete individual fields within a metadata object, you can use the following approach:

1. Call GET <resource>/partner_metadata to read existing metadata.
2. Modify the returned object as needed.
3. Call PUT <resource>/partner_metadata to save the modified metadata.

Delete metadata

To delete the metadata associated with a specific object, you can call PUT <resource>/partner_metadata and pass an empty object {} as the metadata value:

curl -X PUT 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"metadata": {}}'