> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Counterparts
> Learn how to manage the suppliers and customers that will appear on invoices.
## Overview
**Counterparts** represent the suppliers and clients of an [organization](/finops/guides/organizations/index). They can be *organizations* or *individuals*.
A counterpart must be created before an organization can create [invoices, quotes](/finops/guides/accounts-receivable/index), and other documents.
## Roles and permissions
To use the `/counterparts*` endpoints with an [organization user token](/finops/guides/organizations/users#get-organization-user-token), this organization user must have a [role](/finops/guides/organizations/users#create-role) with the `counterpart` permission.
If using a [partner-level token](/finops/guides/authentication/client-credentials), no special permissions are needed.
## Create a counterpart
To create a new counterpart, call [`POST /counterparts`](/finops/reference/openapi/counterparts/post-counterparts) with the request body containing the name, address, contact information, and other details.
```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/counterparts' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "organization",
"is_vendor": false,
"is_customer": true,
"organization": {
"legal_name": "Beskar Steelworks",
"phone": "8886834583",
"email": "info@beskarsteel.com",
"address": {
"country": "MN",
"city": "Keldabe",
"postal_code": "02215",
"state": "MA",
"line1": "1 Forge Road",
"line2": ""
}
},
"language": "en",
"tax_id": "1234567890"
}'
```
```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/counterparts' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "individual",
"is_vendor": false,
"is_customer": true,
"individual": {
"first_name": "Sheev",
"last_name": "Palpatine",
"phone": "",
"email": "sidious@sithlords.com",
"address": {
"country": "CO",
"city": "Coruscant",
"postal_code": "10119",
"state": "",
"line1": "Senate building",
"line2": ""
}
},
"language": "en",
"tax_id": "12 345 678 901"
}'
```
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, Tesouro checks whether or not the organization'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.
```json lines theme={null}
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2023-01-30T12:51:09.299Z",
"updated_at": "2023-01-30T12:51:09.299Z",
"created_by_entity_user_id": "0ac6962b-2aad-4dd1-b2a1-912b0b741437",
"default_billing_address_id": "912b0b741437-4562-b2a1-0ac6962bf",
"default_shipping_address_id": null,
"language": "en",
"type": "organization",
...
}
```
After creating a counterpart, make sure to specify additional information about this counterpart:
* [Addresses](/finops/guides/common/counterparts/addresses), [contacts](/finops/guides/common/counterparts/contacts) - required to [issue invoices](/finops/guides/accounts-receivable/invoices/create) to this counterpart.
* [Bank accounts](/finops/guides/common/counterparts/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 `default_billing_address_id` field of the counterpart object.
If you add additional [addresses](/finops/guides/common/counterparts/addresses) to a counterpart, you can change its default billing address at any time by calling `PATCH /counterparts/{counterpart_id}`.
### Counterpart tax ID
This information applies to [accounts receivable](/finops/guides/accounts-receivable/index).
A common compliance requirement for certain transaction types is to include the customer's taxpayer ID in invoices, if available.
#### Tax 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 a social security number (SSN), taxpayer number, passport number, national ID, or similar.
Tesouro does not validate tax IDs in national registries and does not check the value format.
The organization is responsible for providing the correct data about its counterparts.
Invoices will include the counterpart's tax IDs whether or not they are valid.
#### Check if tax ID is required
Tesouro API follows these conventions:
* Organization-type counterparts require at least one tax ID specified.
* Individual-type counterparts generally do not require a tax ID.
A counterpart can be created successfully even without a tax ID.
But if these values are required for invoices to be [compliant](/finops/guides/accounts-receivable/regulatory-compliance/countries), 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`](/finops/reference/openapi/receivables/get-receivables-required-fields) to check whether `tax_id` is required for organization-type or individual-type counterparts from a specific country. (In the example below, spaces are added for readability.)
```lines theme={null}
GET /receivables/required-fields
? counterpart_country =
& counterpart_type =
```
If a counterpart already exists but not necessarily has a `tax_id` filled in, you can instead use:
```lines theme={null}
GET /receivables/required-fields
? counterpart_id = <...>
& counterpart_billing_address_id = <...>
```
This takes into account the country and type of the organization making the API call to determine country-specific regulatory requirements for invoices.
The response indicates whether the `tax_id` is required for said counterpart:
```json {5, 9} lines theme={null}
{
"counterpart": {
"tax_id": {
"description": "...",
"required": false
}
},
...
}
```
## Counterpart auto-linking and auto-creation
### Auto-linking
Every time a payable is [created via OCR](/finops/guides/accounts-payable/payables/collect), [updated](/finops/guides/accounts-payable/payables/manage#update-a-payable), or [approved for payment](/finops/reference/openapi/payables/post-payables-id-approve-payment-operation), Tesouro [OCR](/finops/support/glossary#ocr) checks if the `counterpart_id` is present in the payable. In case the `counterpart_id` is `null`, Tesouro uses the other counterpart information found in the payable to perform a search in the organization's database on this sequence:
1. Tax ID (`tax_id` field)
2. 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. Tesouro then searches 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 organization's database, i.e. this counterpart already exists in the Tesouro system, the payable is then automatically linked to the counterpart found, avoiding any manual work. Tesouro 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, Tesouro 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`
* `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, Tesouro 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](/finops/guides/accounts-payable/approvals/manual-transition#start-approval),
[approved](/finops/guides/accounts-payable/approvals/manual-transition#confirm-for-payment), marked as
[partially](/finops/guides/accounts-payable/approvals/manual-transition#mark-as-partially-paid) or
[completely](/finops/guides/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](/finops/guides/common/counterparts/addresses) and [bank accounts](/finops/guides/common/counterparts/bank-accounts), 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 Tesouro system, Tesouro fills the payable with the sub-resource information stored in the Tesouro system (the default register, when applicable).
* If the sub-resource information is found in the payable, Tesouro checks if this information already exists in the Tesouro system:
* If the sub-resource information is found in the payable but is not present in the Tesouro system, Tesouro automatically creates these counterpart sub-resources in the Tesouro 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 **disabled** by default.
The auto-linking and auto-creation features are configured at the [partner's](/finops/support/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`](/finops/reference/openapi/partner-settings/patch-settings) endpoint:
```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/settings' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"payable": {
"allow_counterpart_autolinking": true,
"allow_counterpart_autocreation": true
}
}'
```
## Retrieve a counterpart
To get information about a specific counterpart, call [`GET /counterparts/{counterpart_id}`](/finops/reference/openapi/counterparts/get-counterparts-id) as shown:
```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/counterparts/3fa85f64...2c963f66afa6' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
The successful response returns information about the counterpart with the `counterpart_id` provided.
```json lines theme={null}
{
"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",
"default_billing_address_id": "912b0b741437-4562-b2a1-62bf0ac69",
...
}
```
## List all counterparts
To get a list of all of an organization's counterparts, call [`GET /counterparts`](/finops/reference/openapi/counterparts/get-counterparts) as shown:
```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/counterparts' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
The successful response returns an array containing all of an organization's counterparts.
### Sort and filter counterparts
You can sort the returned counterparts by name, and filter the results by ID, name, address, email address, and other fields. For a list of available sort and filter parameters, see the description of the [`GET /counterparts`](/finops/reference/openapi/counterparts/get-counterparts) endpoint. Here are some 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=US` - get all counterparts registered in the United States (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}`](/finops/reference/openapi/counterparts/patch-counterparts-id):
```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/counterparts/411dcb...289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"default_billing_address_id": "f8c95f64-5717-ds6p-b3fc-2c963f2aada6",
"tax_id": "12345678",
"language": "en",
"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.
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 lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/counterparts/411dcb...289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_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
To delete an existing counterpart, call [`DELETE /counterparts/{counterpart_id}`](/finops/reference/openapi/counterparts/delete-counterparts-id):
```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/counterparts/411dcb...289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```