# List counterparties 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. - HTTP method: `GET` - Path: `/api/v1/counterparties` - URL: `https://api.invunion.com/api/v1/counterparties` - Required scope: `counterparties:read` - HTML docs: https://www.invunion.com/knowledge-base/api/list-counterparties/ - Markdown docs: https://www.invunion.com/knowledge-base/api/list-counterparties.md ## Query parameters | Name | Type | Required | Description | Allowed values | Example | | --- | --- | --- | --- | --- | --- | | `page` | integer | optional | Page number. Default 1. | | `1` | | `pageSize` | integer | optional | Page size. Default 20. | | `20` | | `sortBy` | string, no maximum | optional | Sort column. Default name_original. | `account_code`, `name_original`, `name_display`, `status`, `category`, `city`, `country`, `created_at`, `updated_at`, `payer_score`, `total_revenue`, `unmatched_transactions_count` | | | `sortOrder` | string, no maximum | optional | Sort direction. Default asc. | `asc`, `desc` | | | `search` | string, no maximum | optional | Case-insensitive match on name_original, name_display, vat_number, account_code, city, or country. | | `Leones Cars` | | `status` | string, no maximum | optional | Filter by computed payment status from overdue invoices. | `late`, `up_to_date` | | | `category` | string, no maximum | optional | Filter by legal form. | `individual`, `professional`, `governmental` | | | `country` | string, no maximum | optional | ISO 3166-1 alpha-2 country code, or a free-text country name. | | `FR` | | `is_supplier` | boolean | optional | If true, only counterparties flagged as suppliers. | `true`, `false` | | | `is_client` | boolean | optional | If true, only counterparties flagged as clients. | `true`, `false` | | | `is_partner` | boolean | optional | If true, only counterparties flagged as partners. | `true`, `false` | | | `is_payer` | boolean | optional | If true, only counterparties flagged as payers. | `true`, `false` | | | `is_internal` | boolean | optional | If true, only internal counterparties. | `true`, `false` | | | `is_employee` | boolean | optional | If true, only employee counterparties. | `true`, `false` | | | `payerCategory` | string, no maximum | optional | Filter by payer score band. insufficient means no score yet. | `good`, `watch`, `risky`, `insufficient` | | | `minScore` | number | optional | Minimum payer_score (0-100). | | `70` | | `maxScore` | number | optional | Maximum payer_score (0-100). | | `100` | | `hasUnmatchedInvoices` | boolean | optional | If true, only counterparties with open issued invoices. If false, only those without. | `true`, `false` | | | `hasUnmatchedTransactions` | boolean | optional | If true, only counterparties with unmatched settlement-eligible transactions. If false, only those without. | `true`, `false` | | ## Errors | 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. | ## Request (curl) ```bash 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' ``` ## Request (Python) ```python 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()) ``` ## Request (Ruby) ```ruby 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 ``` ## Request (JavaScript) ```javascript 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(); ``` ## Request (Go) ```go 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)) } ``` ## Request (Node) ```javascript 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()); ``` ## Success (200) ```json { "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 } } ```