> This page is for version v2024-01-31.
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Counterparts

## Overview

**Counterparts** represent the suppliers and clients of an [entity](../../entities/index). They can be *organizations* or *individuals*.

A counterpart must be created before an entity create [invoices, quotes](../../accounts-receivable/index), and other documents.

## Roles and permissions \[#permissions]

To use the `/counterparts*` endpoints with an  [entity user token](../../entities/users#get-entity-user-token), this entity user must have a [role](../../entities/users#create-role) with the `counterpart` permission.

If using a [partner-level token](../../get-started/credentials#generate-partner-token), no special permissions are needed.

## Create a counterpart \[#create]

To create a new counterpart, call [`POST /counterparts`](/v2024-01-31/api/counterparts/post-counterparts) with the request body containing the name, address, contact information, and other details.

#### Organization

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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": "acme@example.com",
         "address": {
           "country": "DE",
           "city": "Berlin",
           "postal_code": "10119",
           "state": "BE",
           "line1": "Flughafenstrasse 52",
           "line2": "Additional address"
         }
       },
       "language": "fr",
       "tax_id": "123456789"
     }'
```

#### Individual

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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": "asingh@example.com",
         "address": {
            "country": "DE",
            "city": "Berlin",
            "postal_code": "10115",
            "state": "BE",
            "line1": "Flughafenstrasse 52",
            "line2": "Additional address"
         }
       },
       "tax_id": "123456789"
     }'
```

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.

> **Info**
>
> **Notes on tax/VAT IDs**
>
> If the entity will [issue invoices](../../accounts-receivable/invoices/create) to this counterpart, make sure to provide either the counterpart's `tax_id` (taxpayer identification number), [VAT ID](vat-ids) (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, the `tax_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](https://entreprendre.service-public.fr/vosdroits/F32135?lang=en) number.
> * For businesses in the Netherlands, the `tax_id` is the [Dutch Business Register number](https://business.gov.nl/starting-your-business/registering-your-business/lei-rsin-vat-and-kvk-number-which-is-which/) (KVK).
> * Local sales in Lesotho require that the counterpart has both `tax_id` and [VAT ID](./vat-ids) specified.
> * A Liberian counterpart's tax number must be specified as its [VAT ID](./vat-ids) rather than the `tax_id`.

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

```json
{
  "default_shipping_address_id": null,
  "default_billing_address_id": "912b0b741437-4562-b2a1-0ac6962bf",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-01-30T12:51:09.299Z",
  "updated_at": "2023-01-30T12:51:09.299Z",
  "type": "organization",
  "language": "fr",
  "reminders_enabled": true,
  "created_by_entity_user_id":"0ac6962b-2aad-4dd1-b2a1-912b0b741437",
  ...
}
```

> **Info**
>
> **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](../../accounts-receivable/regulatory-compliance/countries) checks specific to those regions of Spain.

After creating a counterpart, make sure to specify additional information about this counterpart:

* [VAT IDs](./vat-ids), [addresses](./addresses), [contacts](./contacts) - required to [issue invoices](../../accounts-receivable/invoices/create) to this counterpart.
* [Bank accounts](./bank-accounts) - required to make bank-to-bank payments to this counterpart.

### Auto-linking

Every time a payable is [created via OCR](../../accounts-payable/payables/collect), [updated](../../accounts-payable/payables/manage#update-a-payable), or [approved for payment](/v2024-01-31/api/payables/post-payables-id-approve-payment-operation), Monite [OCR](../../references/glossary#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](../../references/glossary#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.

> **AI-Powered counterpart suggestions**
>
> 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:
>
> * `name`
> * `address`
> * `vat`
> * `bank_account`
>
> If 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`.

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

> **Note**
>
> The auto-creation occurs **only** when the payable is [submitted for approval](../../accounts-payable/approvals/manual-transition#start-approval), marked as [partially](../../accounts-payable/approvals/manual-transition#mark-as-partially-paid) or [completely](../../accounts-payable/approvals/manual-transition#mark-as-paid) paid. Before this point, users are able to update the payable and new data for the [auto-linking](#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](./addresses), [bank accounts](./bank-accounts), and [VAT IDs](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](../../references/glossary#partner) 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`](/v2024-01-31/api/partner-settings/patch-settings) endpoint:

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payable": {
         "allow_counterpart_autolinking": true,
         "allow_counterpart_autocreation": true
       }
     }'
```

> **Note**
>
> 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}`](/v2024-01-31/api/counterparts/get-counterparts-id) as shown:

```sh
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/3fa85f64...2c963f66afa6' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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.

```json
{
  "default_shipping_address_id": null,
  "default_billing_address_id": "912b0b741437-4562-b2a1-62bf0ac69",
  "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",
  "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": "asingh@example.net
  }
}
```

## List all counterparts

To get a list of all of an entity's counterparts, call [`GET /counterparts`](/v2024-01-31/api/counterparts/get-counterparts) as shown:

```sh
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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 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`](/v2024-01-31/api/counterparts/get-counterparts) endpoint.  For example, the following request will return all counterparts whose IBAN matches the value provided:

```sh
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts?iban=GB33BUKB2020..5555' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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 (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}`](/v2024-01-31/api/counterparts/patch-counterparts-id):

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
       "tax_id": "NL123456789B12",
       "language": "nl",
       "individual": {
         "first_name": "Dana",
         "last_name": "Cruz",
       }
     }'
```

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

> **Note**
>
> 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:

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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",
       "organization": {}
     }'
```

## Delete a counterpart \[#delete]

To delete an existing counterpart, call [`DELETE /counterparts/{counterpart_id}`](/v2024-01-31/api/counterparts/delete-counterparts-id):

```sh
curl -X DELETE 'https://api.sandbox.monite.com/v1/counterparts/411dcb...289b3' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```