List counterparties

GET https://api.invunion.com/api/v1/counterparties counterparties:read Markdown

List counterparties for the authenticated tenant.

Returns a paginated list of counterparties. Filters are optional and combine with AND. Without filters, system counterparties are listed first. Each item includes computed payment status, billed revenue, and unmatched invoice and transaction counts.

Query parameters

Name	Type	Required
`page` Page number. Default 1. Example: 1	integer	Optional
`pageSize` Page size. Default 20. Example: 20	integer	Optional
`sortBy` Sort column. Default name_original.	string No maximum	Optional
Allowed values`account_codename_originalname_displaystatuscategorycitycountrycreated_atupdated_atpayer_scoretotal_revenueunmatched_transactions_count`
`sortOrder` Sort direction. Default asc. Allowed values`ascdesc`	string No maximum	Optional
`search` Case-insensitive match on name_original, name_display, vat_number, account_code, city, or country. Example: Leones Cars	string No maximum	Optional
`status` Filter by computed payment status from overdue invoices. Allowed values`lateup_to_date`	string No maximum	Optional
`category` Filter by legal form.	string No maximum	Optional
Allowed values`individualprofessionalgovernmental`
`country` ISO 3166-1 alpha-2 country code, or a free-text country name. Example: FR	string No maximum	Optional
`is_supplier` If true, only counterparties flagged as suppliers. Allowed values`truefalse`	boolean	Optional
`is_client` If true, only counterparties flagged as clients. Allowed values`truefalse`	boolean	Optional
`is_partner` If true, only counterparties flagged as partners. Allowed values`truefalse`	boolean	Optional
`is_payer` If true, only counterparties flagged as payers. Allowed values`truefalse`	boolean	Optional
`is_internal` If true, only internal counterparties. Allowed values`truefalse`	boolean	Optional
`is_employee` If true, only employee counterparties. Allowed values`truefalse`	boolean	Optional
`payerCategory` Filter by payer score band. insufficient means no score yet.	string No maximum	Optional
Allowed values`goodwatchriskyinsufficient`
`minScore` Minimum payer_score (0-100). Example: 70	number	Optional
`maxScore` Maximum payer_score (0-100). Example: 100	number	Optional
`hasUnmatchedInvoices` If true, only counterparties with open issued invoices. If false, only those without. Allowed values`truefalse`	boolean	Optional
`hasUnmatchedTransactions` If true, only counterparties with unmatched settlement-eligible transactions. If false, only those without. Allowed values`truefalse`	boolean	Optional

Errors

This operation can return the following errors in addition to generic HTTP failures.

Error	HTTP code	Description
`Missing Bearer token`	401	The Authorization header is missing or is not a Bearer token.
`Invalid or revoked API key`	401	The API key is unknown, malformed, expired, or has been revoked.
`API key is missing scope counterparties:read`	403	The key does not include counterparties:read. A write scope does not imply the matching read scope.
`Too many requests, please try again later`	429	Wait and retry. The Retry-After header is the number of seconds to wait.
`Tenant ID required`	400	The authenticated credential is not bound to a tenant.
`Internal server error`	500	Unexpected server error. The JSON body includes correlationId. Retry with backoff.

Previous: Authentication Next: Get counterparty

Request

Requests in the examples call https://api.invunion.com/api/v1/counterparties.

curl --request GET \
  --url https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'

import requests

url = "https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
}
response = requests.get(url, headers=headers)
print(response.json())

require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY'
response = http.request(request)
puts response.body

const response = await fetch("https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
const data = await response.json();

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

const response = await fetch("https://api.invunion.com/api/v1/counterparties?page=1&pageSize=20", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
console.log(await response.json());

200

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name_original": "Leones Cars",
        "name_display": "Leones Cars",
        "account_code": "CPT-042",
        "category": "professional",
        "payment_terms_days": 30,
        "is_supplier": false,
        "is_client": true,
        "is_partner": false,
        "is_payer": true,
        "is_internal": false,
        "is_employee": false,
        "external_reference": "ERP-1842",
        "vat_number": "FR12345678901",
        "registration_number": "123456789",
        "electronic_address": "0208:123456789",
        "address": "12 Grove Street",
        "city": "Lyon",
        "postal_code": "69001",
        "country": "FR",
        "email": "carl@leonescars.fr",
        "phone": "+33472000000",
        "analytic_1": "SALES-EU",
        "analytic_2": "CHANNEL-DIRECT",
        "status": "up_to_date",
        "payer_score": 88,
        "payer_score_category": "good",
        "payment_score": 92,
        "avg_payment_days": 18,
        "total_invoiced": "12500.00",
        "total_revenue": 12500,
        "total_paid": "9800.00",
        "last_invoice_date": "2026-09-01",
        "last_payment_date": "2026-09-12",
        "invoice_count": 14,
        "outstanding_credit": "0.00",
        "unmatched_invoices_count": 2,
        "unmatched_transactions_count": 1,
        "is_system": false,
        "created_at": "2026-03-04T12:40:56.656Z",
        "updated_at": "2026-09-12T08:15:22.110Z",
        "metadata": {
          "erp_id": "C-1842"
        }
      },
      {
        "id": "4b7a91c2-18e4-4d6f-a8c1-9e2d5f0b73a1",
        "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name_original": "Grove Street Garage",
        "name_display": "Grove Street Garage",
        "account_code": "CPT-043",
        "category": "professional",
        "payment_terms_days": 15,
        "is_supplier": true,
        "is_client": false,
        "is_partner": false,
        "is_payer": false,
        "is_internal": false,
        "is_employee": false,
        "external_reference": "ERP-1904",
        "vat_number": "US987654321",
        "registration_number": "987654321",
        "electronic_address": null,
        "address": "88 Grove Street",
        "city": "Los Angeles",
        "postal_code": "90012",
        "country": "US",
        "email": "accounts@grovestreet.example",
        "phone": "+12135550190",
        "analytic_1": "PROCURE-US",
        "analytic_2": "CHANNEL-PARTNER",
        "status": "up_to_date",
        "payer_score": null,
        "payer_score_category": "insufficient",
        "payment_score": null,
        "avg_payment_days": null,
        "total_invoiced": "0.00",
        "total_revenue": 0,
        "total_paid": "4200.00",
        "last_invoice_date": null,
        "last_payment_date": "2026-09-08",
        "invoice_count": 0,
        "outstanding_credit": "0.00",
        "unmatched_invoices_count": 0,
        "unmatched_transactions_count": 1,
        "is_system": false,
        "created_at": "2026-04-18T09:12:00.000Z",
        "updated_at": "2026-09-08T14:22:11.000Z",
        "metadata": {
          "erp_id": "S-1904"
        }
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}