Counterparts
Learn how to manage the suppliers and customers that will appear on invoices.
Counterparts represent the suppliers and clients of an entity. They can be organizations or individuals.
A counterpart must be created before an entity create invoices, quotes, and other documents.
To use the /counterparts* endpoints with an entity user token, this entity user must have a role with the counterpart permission.
If using a partner-level token, no special permissions are needed.
To create a new counterpart, call POST /counterparts with the request body containing the name, address, contact information, and other details.
The language field in the payload of the POST /counterparts request determines the language on all PDF documents for the counterpart. If the counterpart language is not provided, Monite checks whether or not the entity’s settings object contains a default language and creates PDF documents in that language. If neither is available, all PDF documents for the counterpart will be in English.
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.
tax_id is required for counterparts who are not VAT-registered.individual type, the tax_id can be a government-issued identification number such as the taxpayer number, passport number, national ID, or similar.tax_id is the SIREN/SIRET number.tax_id is the Dutch Business Register number (KVK).tax_id and VAT ID specified.tax_id.The successful response contains the unique id assigned to this counterpart, along with other information.
Counterpart addresses
When creating a counterpart—individual or organization, Monite creates an address for the counterpart using the information provided in the address field. This address becomes the counterpart’s default billing address and can be accessed using the default_billing_address_id field on the counterpart object. You can update this field after creating other counterpart addresses by making a PATCH request to the /counterparts/{counterpart_id} endpoint.
Spanish counterparts registered in the Canary Islands must use the country code IC instead of ES in their address.
Spanish counterparts registered in Ceuta and Melilla must use EA as the address country code.
This is required for Monite to apply the regulatory compliance checks specific to those regions of Spain.
After creating a counterpart, make sure to specify additional information about this counterpart:
Every time a payable is created via OCR, updated, or approved for payment, 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 on this sequence:
tax_id field)iban field)sort_code + account_number fields)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, Sort code AND account number, 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.
When a user uploads a payable, Monite automatically analyzes the payable data and uses AI to suggest the most likely matching counterpart. The suggestion is based on the similarity of the following fields:
nameaddressvatbank_accountIf no sufficiently similar counterpart is found, no suggestion will be generated.
To get the suggested counterpart for a specific payable, call GET /payables/{payable_id}/suggestions.
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 is_vendor field is 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.
The counterparts sub-resources, which are addresses, bank accounts, and VAT IDs, can also be set during the auto-creation process, following this logic:
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:
The auto-linking and auto-creation features are disabled by default.
To get information about a specific counterpart, call GET /counterparts/{counterpart_id} as shown:
The successful response returns information about the counterpart with the counterpart_id provided.
To get a list of all of an entity’s counterparts, call GET /counterparts as shown:
The successful response returns an array containing all of an entity’s counterparts.
You can sort the returned counterparts by name, and filter the results by ID, 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:
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 (the address.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.To edit an existing counterpart, call PATCH /counterparts/{counterpart_id}:
Updating the language field of a counterpart will also update the language on all PDF documents created for that counterpart.
All PATCH requests to the endpoint must include the counterpart’s type 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, the following snippet updates the counterpart’s default_shipping_address_id and default_billing_address_id fields:
To delete an existing counterpart, call DELETE /counterparts/{counterpart_id}: