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. When you collect incoming invoices, vendor information is also captured as counterparts.

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-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "organization",
  "organization": {
    "legal_name": "Acme Inc.",
    "vat_number": "123456789",
    "is_vendor": false,
    "is_customer": true,
    "phone": "+4930774619876",
    "email": "[email protected]",
    "registered_address": {
      "country": "DE",
      "city": "Berlin",
      "postal_code": "10119",
      "state": "",
      "line1": "Street and house number",
      "line2": "Additional address"
    },
    "contacts": [
      {
        "first_name": "Kevin",
        "last_name": "Hueber",
        "title": "Mr.",
        "email": "[email protected]",
        "phone": "+4930774619876",
        "is_default": true,
        "address": {
          "country": "DE",
          "city": "Berlin",
          "postal_code": "10115",
          "state": "",
          "line1": "Street and house number",
          "line2": "Additional address"
        }
      }
    ]
  }
}'

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

{
  "type": "individual",
  "individual": {
      "first_name": "FirstName",
      "last_name": "LastName",
      "phone": "+15551231234",
      "email": "[email protected]",
      "tax_id": "13243546",
      "is_vendor": false,
      "is_customer": true,
      "residential_address": {
         "country": "DE",
         "city": "Berlin",
         "postal_code": "10115",
         "state": "BE",
         "line1": "Street and house number",
         "line2": "Additional address"
      }
  }
}

📘

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

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, 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?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}.

Manage a counterpart's bank accounts

Add a bank account to the counterpart

Counterparts that represent an entity's vendors or suppliers can have bank account information associated with them. The bank account information can be used to pay the invoices issued by those counterparts.

To add a bank account to a counterpart, call POST /counterparts/{counterpart_id}/bank_accounts:

curl -X POST 'https://api.sandbox.monite.com/v1/counterparts/{counterpart_id}/bank_accounts' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Personal account",
       "iban": "GB33BUKB20201555555555",
       "bic": "GB33BUKB202"
     }'

The successful response returns the information about the bank account:

{
  "name": "Personal account",
  "iban": "GB33BUKB20201555555555",
  "bic": "GB33BUKB202",
  "id": "04476eb4-121e-44dd-8a0d-1bcaa9246265",
  "counterpart_id": "3a9c5924-2c3f-47af-905a-e4c7efe548df"
}

List all bank accounts

To get information about all bank accounts associated with the specified counterpart, call GET /counterparts/{counterpart_id}/bank_accounts.

Retrieve a bank account

To get information about a specific bank account associated with the specified counterpart, call GET /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}.

Edit a bank account

To edit an existing bank account of the specified counterpart, call PATCH /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}.

Delete a bank account

To delete an existing bank account from the list of bank accounts associated with the specified counterpart, call DELETE /counterparts/{counterpart_id}/bank_accounts/{bank_account_id}.


Did this page help you?