Counterparts

Overview

Counterparts represent the suppliers and clients of an entity. They can be organizations or individuals.

A counterpart must be created before an entity 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 the counterpart 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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "type": "organization",
8
       "organization": {
9
         "legal_name": "Acme GmbH",
10
         "is_vendor": false,
11
         "is_customer": true,
12
         "phone": "+4930774619876",
13
         "email": "acme@example.com",
14
         "address": {
15
           "country": "DE",
16
           "city": "Berlin",
17
           "postal_code": "10119",
18
           "state": "",
19
           "line1": "Flughafenstrasse 52",
20
           "line2": ""
21
         }
22
       },
23
       "language": "de",
24
       "tax_id": "12/345/67890"
25
     }'

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.

The successful response contains the unique id assigned to this counterpart, along with other information.

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "created_at": "2023-01-30T12:51:09.299Z",
4
  "updated_at": "2023-01-30T12:51:09.299Z",
5
  "created_by_entity_user_id": "0ac6962b-2aad-4dd1-b2a1-912b0b741437",
6
  "default_billing_address_id": "912b0b741437-4562-b2a1-0ac6962bf",
7
  "default_shipping_address_id": null,
8
  "language": "de",
9
  "type": "organization",
10
  ...
11
}

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.

Counterpart address

The address specified when creating a counterpart becomes its default billing address for invoices. The ID of this address is saved to the udefault_billing_address_id field of the counterpart object.

If you add additional addresses to a counterpart, you can change its default billing address at any time by calling PATCH /counterparts/{counterpart_id}.

Counterpart tax ID and VAT ID

A common compliance requirement for certain transation types is to include the customer’s taxpayer ID or VAT ID in invoices, it available. For example, intra-EU B2B sales require the customer’s VAT ID in invoices.

Depending on the counterpart’s country and type (organization or individual), it may have both tax and VAT IDs or only one of them. In some countries, the tax ID is the same as VAT ID.

Tax and VAT ID examples

• For organizations, tax_id can be the taxpayer number or a similar business identifier.
• For individuals, tax_id can be a government-issued identification number such as the taxpayer number, passport number, national ID, or similar.
• VAT ID numbers are added via /counterparts/{counterpart_id}/vat_ids endpoints.

Below are some examples of which values to provide in tax_id and VAT ID for various countries:

^* Liberian tax number needs to be specified as the counterpart’s VAT ID rather than as its tax_id.

Check if tax ID or VAT ID is required

Monite API follows these conventions:

• Organization-type counterparts require at least one of tax ID or VAT ID specified. If the counterpart is registered for VAT, we expect that the VAT ID is specified. If the counterpart is not VAT-registered, then tax ID is required.

• Individual-type counterparts generally do not require a tax ID but may require a VAT ID. An exception are local B2B sales in Lesotho where counterparts require a tax_id.

A counterpart can be created successfully even without a tax ID and VAT ID. But if these values are required for invoices to be compliant, invoices will fail to be issued to this counterpart unless the missing values are provided.

Before creating a counterpart, you can use GET /receivables/required_fields to check whether tax_id or VAT ID is required for organization-type or individual-type counterparts from a specific country. (In the example below, spaces are added for readability.)

GET /receivables/required_fields
  ? counterpart_country = <two-letter country code>
  & counterpart_type    = <organization | individual>
  [ & entity_vat_id_id  = <...> ]

If a counterpart already exists but not necessarily has a tax_id or VAT ID filled in, you can instead use:

GET /receivables/required_fields
  ? counterpart_id = <...>
  & counterpart_billing_address_id = <...>
  [ & entity_vat_id_id  = <...> ]

This takes into account the country and type of the entity making the API call to determine country-specific regulatory requirements for invoices. If the entity has a VAT ID, include it in the request parameters.

The response indicates whether the tax_id and/or VAT ID are required for said counterpart:

1
{
2
  "counterpart": {
3
    "tax_id": {
4
      "description": "...",
5
      "required": false
6
    },
7
    "vat_id": {
8
      "description": "...",
9
      "required": true
10
    }
11
  },
12
  ...
13
}

Counterpart auto-linking and auto-creation

Auto-linking

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:

1. Tax ID (tax_id field)
2. IBAN (iban field)
3. Sort code AND account number (sort_code + account_number fields)
4. 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, 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.

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

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:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4
     -H 'Content-Type: application/json' \
5
     -d '{
6
       "payable": {
7
         "allow_counterpart_autolinking": true,
8
         "allow_counterpart_autocreation": true
9
       }
10
     }'

Retrieve a counterpart

To get information about a specific counterpart, call GET /counterparts/{counterpart_id} as shown:

1
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/3fa85f64...2c963f66afa6' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' 

The successful response returns information about the counterpart with the counterpart_id provided.

1
{
2
  "id": "2e557c1e-db8b-48f9-8860-49336ef6fbab",
3
  "created_at": "2023-06-22T11:44:48.630894+00:00",
4
  "updated_at": "2023-06-22T11:44:48.630905+00:00",
5
  "default_billing_address_id": "912b0b741437-4562-b2a1-62bf0ac69",
6
  ...
7
}

List all counterparts

To get a list of all of an entity’s counterparts, call GET /counterparts as shown:

1
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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 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:

1
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts?iban=GB33BUKB2020..5555' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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 (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.

Edit a counterpart

To edit an existing counterpart, call PATCH /counterparts/{counterpart_id}:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
8
       "tax_id": "12345678",
9
       "language": "nl",
10
       "individual": {
11
         "first_name": "Dana",
12
         "last_name": "Cruz"
13
       }
14
     }'

Updating the language field of a counterpart will also update the language on all PDF documents created for that counterpart.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "default_shipping_address_id": "0ac3fa2b-2aad-4dd1-f8c9-4h5h963b741437",
8
       "default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
9
       "organization": {}
10
     }'

Delete a counterpart

To delete an existing counterpart, call DELETE /counterparts/{counterpart_id}:

1
curl -X DELETE 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'