Counterparts
Learn how to manage the suppliers and customers that will appear on invoices.
Overview
Counterparts represent the suppliers and clients of an entity. They can be organizations or individuals.
A counterpart must be created before you can create invoices, quotes, and other documents.
Roles and permissions
To use the
/counterparts*
endpoints with an entity user token, this entity user must have a role with thecounterpart
permission.If using a partner-level token, no special permissions are needed.
Create a counterpart
To create a new counterpart, call POST /counterparts
with the request body containing the name, address, contact information, and other details.
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "organization",
"organization": {
"legal_name": "Acme Inc.",
"is_vendor": false,
"is_customer": true,
"phone": "+4930774619876",
"email": "[email protected]",
"registered_address": {
"country": "DE",
"city": "Berlin",
"postal_code": "10119",
"state": "BE",
"line1": "Flughafenstrasse 52",
"line2": "Additional address"
}
},
"tax_id": "123456789"
}'
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
-H 'X-Monite-Version: 2023-04-12' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "individual",
"individual": {
"first_name": "Adnan",
"last_name": "Singh",
"title": "Mr.",
"is_vendor": false,
"is_customer": true,
"phone": "5553211234",
"email": "[email protected]",
"residential_address": {
"country": "DE",
"city": "Berlin",
"postal_code": "10115",
"state": "BE",
"line1": "Flughafenstrasse 52",
"line2": "Additional address"
}
},
"tax_id": "123456789"
}'
Notes on tax/VAT IDs
If the entity will issue invoices to this counterpart, make sure to provide either the counterpart's
tax_id
(taxpayer identification number), VAT ID (VAT registration number), or both if available.
- The
tax_id
is required for counterparts who are not VAT-registered.- For counterparts of the
individual
type, thetax_id
can be a government-issued identification number such as the taxpayer number, passport number, national ID, or similar.- For French businesses, the
tax_id
is the SIREN/SIRET number.- For businesses in the Netherlands, the
tax_id
is the Dutch Business Register number (KVK).- Local sales in Lesotho require that the counterpart has both
tax_id
and VAT ID specified.- A Liberian counterpart's tax number must be specified as its VAT ID rather than the
tax_id
.
The successful response contains the unique id
assigned to this counterpart, along with other information.
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2023-01-30T12:51:09.299Z",
"updated_at": "2023-01-30T12:51:09.299Z",
"type": "organization",
"created_automatically": false,
"reminders_enabled": true,
"created_by_entity_user_id":"0ac6962b-2aad-4dd1-b2a1-912b0b741437",
...
}
After creating a counterpart, make sure to specify additional information about this counterpart:
- VAT IDs, Addresses, Contacts - required to issue invoices to this counterpart.
- Bank accounts - required to make bank-to-bank payments to this counterpart.
Auto-linking
Every time a payable is created via OCR or updated, Monite OCR checks if the counterpart_id
is present in the payable. In case the counterpart_id
is null
, Monite uses the other counterpart information found in the payable to perform a search in the entity's database starting with the tax ID. If no tax ID is found, Monite searches for the IBAN, and finally for the exact name AND address (city
, country
, postal_code
, and line1
fields).
The same logic applies if more than one record is found for tax ID. Monite then searches for the IBAN, and finally for the name AND address to make sure the register found is unique. If, by the end of the final verification, there is still more than one counterpart, no counterpart is linked to the payable, i.e. counterpart_id
remains as null
.
If a unique counterpart register is found in the entity's database, i.e. this counterpart already exists in the Monite system, the payable is then automatically linked to the counterpart found, avoiding any manual work. Monite also tries to enrich the counterpart register in the database with the supplied counterpart data.
In this case, the counterpart's is_vendor
field is set to true
to indicate that this counterpart appears in payables.
Auto-creation
When a payable is moved to the paid
, partially_paid
, or waiting_for_approval
statuses, Monite also tries the counterpart auto-linking.
If the counterpart cannot be auto-linked, a new counterpart will be automatically created with the information provided in the payable. The counterpart sub-resources are also created.
In this case, the created_automatically
and is_vendor
fields are set to true
to indicate that this counterpart appears in payables.
If the payable does not have enough information about the counterpart for its auto-creation, the counterpart cannot be created nor linked to the payable.
The auto-creation occurs only when the payable is submitted for approval, marked as partially or completely paid. Before this point, users are able to update the payable and new data for the auto-linking may be provided. Therefore, auto-creation is the final step before freezing the payable data.
Sub-resources
The counterparts sub-resources, which are addresses, bank accounts, and VAT IDs, can also be set during the auto-creation process, following this logic:
- If no sub-resource information is found in the payable but the counterpart already exists in the Monite system, Monite fills the payable with the sub-resource information stored in the Monite system (the default register, when applicable).
- If the sub-resource information is found in the payable, Monite checks if this information already exists in the Monite system:
- If the sub-resource information is found in the payable but is not present in the Monite system, Monite automatically creates these counterpart sub-resources in the Monite system, if the mandatory fields are provided.
- If the payable does not have enough information about the counterpart sub-resources for their auto-creation, the counterpart cannot be created nor linked to the payable.
How to enable auto-linking and auto-creation
The auto-linking and auto-creation features are configured at the partner's settings level via the boolean fields allow_counterpart_autolinking
and allow_counterpart_autocreation
respectively.
To enable or disable the auto-linking or the auto-creation, send a PATCH
request to the /settings
endpoint:
curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"payable": {
"allow_counterpart_autolinking": true,
"allow_counterpart_autocreation": true
}
}'
The auto-linking and auto-creation features are disabled by default.
Retrieve a counterpart
To get information about a specific counterpart, call GET /counterparts/{counterpart_id}
as shown:
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/3fa85f64...2c963f66afa6' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
The successful response returns information about the counterpart with the counterpart_id
provided.
{
"default_shipping_address_id": null,
"default_billing_address_id": null,
"id": "2e557c1e-db8b-48f9-8860-49336ef6fbab",
"created_at": "2023-06-22T11:44:48.630894+00:00",
"updated_at": "2023-06-22T11:44:48.630905+00:00",
"type": "individual",
"created_automatically": false,
"reminders_enabled": false,
"created_by_entity_user_id": "0ac6962b-2aad-4dd1-b2a1-912b0b741437",
"individual": {
"first_name": "test",
"last_name": "test",
"title": "test",
"is_vendor": true,
"is_customer": false,
"phone": "5553211234",
"email": "[email protected]
}
}
List all counterparts
To get a list of all of an entity's counterparts, call GET /counterparts
as shown:
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
The successful response returns an array containing all of an entity's counterparts.
Sort and filter counterparts
You can sort the returned counterparts by name, and filter the results by name, address, IBAN, email address, and other fields. For a list of available sort and filter parameters, see the description of the GET /counterparts
endpoint. For example, the following request will return all counterparts whose IBAN matches the value provided:
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts?iban=GB33BUKB2020..5555' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Here are some other filtering examples:
GET /counterparts?type=organization&sort=counterpart_name
- get the counterparts that are organizations, sorted by name.GET /counterparts?counterpart_name__icontains=net
- get all counterparts whose name contains "net" (case-insensitive).GET /counterparts?address.country=DE
- get all counterparts registered in Germany (theaddress.country
parameter is a two-letter country code).GET /counterparts?created_at__gte=2022-01-01T00%3A00%3A00
- get all counterparts created on or after January 1, 2022.
Edit a counterpart
To edit an existing counterpart, make a PATCH
request to the /counterparts/{counterpart_id}
endpoint as shown:
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"default_shipping_address_id": "0ac3fa2b-2aad-4dd1-f8c9-4h5h963b741437",
"default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
"tax_id": "NL123456789B12",
"type": "individual",
"individual": {
"first_name": "Dana",
"last_name": "Cruz",
}
}'
All
PATCH
requests to the endpoint must include thetype
field and the counterpart'stype
object in the request body. You must provide an empty object if there is no data to be updated within the counterpart type object. For example:
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"default_shipping_address_id": "0ac3fa2b-2aad-4dd1-f8c9-4h5h963b741437",
"default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
"type": "organization",
"organization": {}
}'
Delete a counterpart
To delete an existing counterpart, make a DELETE
request to the /counterparts/{counterpart_id}
endpoint as shown:
curl -X DELETE 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
Updated 20 days ago