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.

The way to work with metadata varies depending on the object type. Refer to the corresponding section below:

• Entity and counterpart metadata
• Payable metadata

Entity and counterpart metadata

Metadata is not part of the Entity and Counterpart 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

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

  }
}

Set metadata

Use PUT <resource>/partner_metadata to add metadata or replace existing metadata for a specific entity or counterpart. For example:

curl -X PUT 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Version: 2023-03-14' \
     -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 a specific entity or counterpart. For example:

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

If there is no metadata associated with the specified entity or counterpart, 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 this 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 entity or counterpart, 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-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"metadata": {}}'

Payable metadata

Metadata format

Payable objects have the partner_metadata field to store partner-provided metadata. The value can be an arbitrary JSON object up to 2000 bytes in size:

{
  "currency": "EUR",
  ...

  "partner_metadata": {
    "custom_field_1": "value",
    "custom_field_2": 42,
    "custom_field_3": true,
    ...
  }
}

If no metadata is associated with the specified payable, the partner_metadata value is an empty object {}.

Set metadata

When creating payables from data, you can provide the partner_metadata object directly in the creation request:

curl -X POST 'https://api.sandbox.monite.com/v1/payables/upload_with_data' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "currency": "EUR",
       "amount": 11900,
       ...
       "partner_metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'

In case of payables created by processing documents with OCR, you can add partner_metadata to a created payable by calling PATCH /payables/{payable_id}:

curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/aa314...5c0' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "partner_metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'

Get metadata

Use GET /payables/{payable_id} to get a single payable along with its metadata, or GET /payables to get all (or a filtered set of) payables along with their metadata.

Sample response from GET /payables:

{
  "data": [
    {
      "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
      ...
      "partner_metadata": {
      "external_id": "id_6c8f1262fdbc",
      "comment": ""
      }
    },
    {
      "id": "f6d57e58-5703-47d4-80c0-2aa2ba0b36c4",
      ...
      "partner_metadata": {}
    },
    ...
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}

Partially update metadata

If you need to add, modify, or delete individual fields within a Payable object's metadata, you can use this approach:

1. Call GET /payables/{payable_id} and read the partner_metadata response field to get existing metadata.
2. Modify the partner_metadata value as needed.
3. Call PATCH /payables/{payable_id} and provide the updated partner_metadata value in the request.

Delete metadata

To delete existing metadata from a payable, call PATCH /payables/{payable_id} and set partner_metadata to an empty object {}:

curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/aa314...5c0' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "partner_metadata": {} }'