Metadata
Learn how to set arbitrary metadata to entities, counterparts, and payables.
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:
- Call
GET <resource>/partner_metadata
to read existing metadata. - Modify the returned object as needed.
- 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": {}}'
Updated 5 months ago