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
`pageSize` Page size. Default 20, maximum 100. Example: 20	integer	Optional
`cursor` Opaque cursor: pass the nextCursor of the previous response. Valid only with the same sortBy, sortOrder, and filters. Omit it for the first page. Example: Y3JlYXRlZF9hdDpkZXNjfDIwMjYtMDktMDhUMTQ6MTA6MDAuMDAwWnw3ZDljMTNlNA	string Max 512	Optional
`includeTotal` total is returned on the first page unless includeTotal=false, and on cursor pages only when includeTotal=true. Skip it to save a count. Allowed values`truefalse`	boolean	Optional
`page` Deprecated. Offset page number kept for older integrations; use cursor instead. Ignored when cursor is sent. Example: 2	integer	Optional
`updatedSince` ISO 8601 instant. Returns only rows modified strictly after it. Use it with cursor for incremental sync. Example: 2026-09-01T00:00:00Z	string No maximum	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	More than 100 requests in one minute from this API key or IP address. Wait for the Retry-After header (seconds) and retry.
`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: Retries and rate limits 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?pageSize=20 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'

import requests

url = "https://api.invunion.com/api/v1/counterparties?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?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?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?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?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": "[email protected]",
        "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": "[email protected]",
        "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,
    "nextCursor": null
  }
}