Counterparts

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.

Create a counterpart

To create a new counterpart, call POST /counterparts.

In the example below, the counterpart is created as an organization:

curl -X POST 'https://api.sandbox.monite.com/v1/counterparts' \
     -H 'X-Monite-Version: 2023-03-14' \
     -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"
        }
      }
    }' 

To create a counterpart as an individual, use the following request body:

{
  "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"
    }
  }
}

The successful response contains information about the created counterpart:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-01-30T12:51:09.299Z",
  "updated_at": "2023-01-30T12:51:09.299Z",
  "type": "individual",
  "created_automatically": false,
  "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"
    }
  },
  "reminders_enabled": true
}

📘

For the complete list of the request body fields and their descriptions, refer to the /counterpart endpoint.

⚠️

Once the counterpart is created, there is additional information about the counterpart to be managed:

• Tax IDs
• Addresses
• Bank accounts
• Contact

Auto-linking and auto-creation

When a new payable is uploaded, the Monite OCR tries to recognize the counterpart information present in the payable. The successfully scanned information about the counterpart is stored in the payable object. Before sending the payable for approval, the user can manually select an existing counterpart from their own database and overwrite the extracted counterpart information.

In case the payable is sent for approval containing only the scanned counterpart information, i.e. without the counterpart manual selection, Monite uses the scanned information 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 name AND address.

There are two possibilities depending on the search result:

• Auto-linking: If a counterpart register is found in the entity's database, i.e. this counterpart already exists in Monite, the payable is then automatically linked to the counterpart found. Monite also tries to enrich the counterpart register in the database with the scanned data.

• Auto-creation: If no register is found in the entity's database, a new counterpart is automatically created with the information provided by the OCR. In this case, the field created_automatically is set to true.

In both cases, the counterpart's is_vendor field is set to true to indicate that this counterpart appears in payables.

List all counterparts

To get a list of all counterparts of an entity, call GET /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.

Some examples:

• GET /counterparts?iban=GB33BUKB20201555555555 - find a counterpart by IBAN.
• 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.

Retrieve a counterpart

To get information about a specific counterpart, call GET /counterparts/{counterpart_id}.

Edit a counterpart

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

Delete a counterpart

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