# Create counterparty Create a counterparty. Creates a customer, supplier, or other third party. name_original is required. If account_code is omitted, Invunion assigns the next CPT-NNN code. By default an empty Default catalog payment method is created. Send payment_method with iban or identifier to also create a catalog instrument linked to this counterparty. Catalog conflicts (aggregator IBAN, exclusive elsewhere) do not roll back the counterparty. - HTTP method: `POST` - Path: `/api/v1/counterparties` - URL: `https://api.invunion.com/api/v1/counterparties` - Required scope: `counterparties:write` - HTML docs: https://www.invunion.com/knowledge-base/api/create-counterparty/ - Markdown docs: https://www.invunion.com/knowledge-base/api/create-counterparty.md ## Body parameters | Name | Type | Required | Description | Allowed values | Example | | --- | --- | --- | --- | --- | --- | | `name_original` | string, max 255 | required | Legal or source name. This is the only required field. Also accepted as name in bulk import. | | `Leones Cars` | | `name_display` | string, max 255 | optional | Display name shown in the product. Defaults to empty when omitted. | | `Leones Cars` | | `account_code` | string, max 50 | recommended | Your account code. Unique per tenant. If omitted, Invunion assigns CPT-NNN. | | `CPT-042` | | `category` | string, max 50 | recommended | Legal form of the counterparty. Default professional. | `individual`, `professional`, `governmental` | | | `payment_terms_days` | integer | optional | Payment terms in days, 0 to 365. If omitted, tenant default applies. | | `30` | | `is_supplier` | boolean | optional | Supplier role. Default false. | `true`, `false` | | | `is_client` | boolean | optional | Client role. Default true on create. | `true`, `false` | | | `is_partner` | boolean | optional | Partner role. Default false. | `true`, `false` | | | `is_payer` | boolean | optional | Payer role. Default false. | `true`, `false` | | | `is_internal` | boolean | optional | Internal entity. Default false. | `true`, `false` | | | `is_employee` | boolean | optional | Employee. Default false. | `true`, `false` | | | `external_reference` | string, max 255 | optional | External reference. Your ERP or billing customer id. Used for identity lookup. | | `ERP-1842` | | `vat_number` | string, max 50 | optional | VAT number. Used for identity lookup on import. | | `FR12345678901` | | `registration_number` | string, max 100 | optional | National ID (SIREN, company number, and similar). | | `123456789` | | `electronic_address` | string, max 255 | optional | E-invoicing address (Peppol and similar). | | `0208:123456789` | | `address` | string, no maximum | optional | Street address. | | `12 Grove Street` | | `city` | string, max 255 | optional | City. | | `Lyon` | | `postal_code` | string, max 20 | optional | Postal code. | | `69001` | | `country` | string, no maximum | optional | Country name or ISO 3166-1 alpha-2 code. Stored as alpha-2. Invalid values return 400 on create. | | `FR` | | `email` | string, no maximum | optional | Contact email. | | `carl@leonescars.fr` | | `phone` | string, max 50 | optional | Phone number. | | `+33472000000` | | `analytic_1` | string, max 100 | optional | Analytic axis 1. | | `SALES-EU` | | `analytic_2` | string, max 100 | optional | Analytic axis 2. | | `CHANNEL-DIRECT` | | `metadata` | object | optional | JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. | | `{"erp_id":"C-1842"}` | | `createDefaultPaymentMethod` | boolean | optional | If false, skip the empty Default catalog payment method. Default true. Independent of payment_method. | `true`, `false` | | | `payment_method` | object | recommended | Optional catalog instrument on this new counterparty. Same fields as POST /payment-methods except counterparty_id (implied). Requires iban or identifier. Aggregator IBANs and exclusive instruments owned elsewhere are skipped; the counterparty is still created. | | | | `payment_method.name` | string, max 255 | optional | Instrument display name. Defaults to name_original. | | `Leones Cars EUR` | | `payment_method.iban` | string, max 50 | recommended | IBAN. Required unless identifier is set. Unique per tenant catalog. BIC alone is not enough. | | `FR7630006000011234567890189` | | `payment_method.identifier` | string, max 120 | optional | Non-IBAN instrument key (PayPal email, wallet id, terminal number). Required unless iban is set. Unique per tenant catalog. | | `carl@leonescars.fr` | | `payment_method.code` | string, max 50 | recommended | Your payment-method code. Unique per tenant. If omitted, Invunion assigns PM-NNN. | | `PM-001` | | `payment_method.type` | string, no maximum | recommended | Instrument type. Default bank_account. | `bank_account`, `credit_card`, `paypal`, `wero`, `twint`, `crypto_wallet`, `other` | | | `payment_method.bic` | string, max 11 | optional | BIC. Bank name and country are filled from the BIC directory when omitted. | | `BNPAFRPP` | | `payment_method.currency` | string, max 3 | optional | ISO 4217 currency code. Default EUR. | | `EUR` | | `payment_method.association_mode` | string, no maximum | recommended | exclusive (one owner) or shared (several counterparties). Default exclusive. Applies only when creating a new catalog instrument; an existing shared IBAN stays shared. | `exclusive`, `shared` | | | `payment_method.account_type` | string, no maximum | optional | Optional account type label. | | `checking` | | `payment_method.bank_name` | string, no maximum | optional | Bank name. Filled from BIC when omitted. | | `BNP Paribas` | | `payment_method.bank_country` | string, no maximum | optional | ISO 3166-1 alpha-2 of the bank, not the counterparty country. | | `FR` | | `payment_method.status` | string, no maximum | optional | Instrument status. Default active. | `active`, `inactive`, `error` | | | `payment_method.metadata` | object | optional | JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. | | `{"erp_pm":"BANK-042"}` | ## 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:write` | `403` | The key does not include counterparties:write. 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. | | `name_original is required` | `400` | The body does not include name_original. | | `Invalid association_mode` | `400` | association_mode is not exclusive or shared. | | `Invalid country` | `400` | country could not be normalised to an ISO 3166-1 alpha-2 code. | | `Tenant ID required` | `400` | The authenticated credential is not bound to a tenant. | | `Counterparty with this name already exists` | `409` | A unique constraint on the tenant rejected the insert. | | `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. | ## Request (curl) ```bash curl --request POST \ --url https://api.invunion.com/api/v1/counterparties \ --header 'accept: application/json' \ --header 'authorization: Bearer uk_live_YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "name_original": "Leones Cars", "name_display": "Leones Cars", "category": "professional", "payment_terms_days": 30, "is_client": true, "is_payer": true, "external_reference": "ERP-1842", "vat_number": "FR12345678901", "country": "FR", "city": "Lyon", "email": "carl@leonescars.fr", "payment_method": { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "type": "bank_account", "association_mode": "exclusive" } }' ``` ## Request (Python) ```python import requests url = "https://api.invunion.com/api/v1/counterparties" headers = { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json", } payload = { "name_original": "Leones Cars", "name_display": "Leones Cars", "category": "professional", "payment_terms_days": 30, "is_client": True, "is_payer": True, "external_reference": "ERP-1842", "vat_number": "FR12345678901", "country": "FR", "city": "Lyon", "email": "carl@leonescars.fr", "payment_method": { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "type": "bank_account", "association_mode": "exclusive" } } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ## Request (Ruby) ```ruby require 'net/http' require 'json' require 'uri' uri = URI("https://api.invunion.com/api/v1/counterparties") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['Accept'] = 'application/json' request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY' request['Content-Type'] = 'application/json' request.body = "{\n \"name_original\": \"Leones Cars\",\n \"name_display\": \"Leones Cars\",\n \"category\": \"professional\",\n \"payment_terms_days\": 30,\n \"is_client\": true,\n \"is_payer\": true,\n \"external_reference\": \"ERP-1842\",\n \"vat_number\": \"FR12345678901\",\n \"country\": \"FR\",\n \"city\": \"Lyon\",\n \"email\": \"carl@leonescars.fr\",\n \"payment_method\": {\n \"name\": \"Leones Cars EUR\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"BNPAFRPP\",\n \"type\": \"bank_account\",\n \"association_mode\": \"exclusive\"\n }\n}" response = http.request(request) puts response.body ``` ## Request (JavaScript) ```javascript const response = await fetch("https://api.invunion.com/api/v1/counterparties", { method: "POST", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ "name_original": "Leones Cars", "name_display": "Leones Cars", "category": "professional", "payment_terms_days": 30, "is_client": true, "is_payer": true, "external_reference": "ERP-1842", "vat_number": "FR12345678901", "country": "FR", "city": "Lyon", "email": "carl@leonescars.fr", "payment_method": { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "type": "bank_account", "association_mode": "exclusive" } }), }); const data = await response.json(); ``` ## Request (Go) ```go package main import ( "bytes" "fmt" "io" "net/http" ) func main() { payload := []byte(`{ "name_original": "Leones Cars", "name_display": "Leones Cars", "category": "professional", "payment_terms_days": 30, "is_client": true, "is_payer": true, "external_reference": "ERP-1842", "vat_number": "FR12345678901", "country": "FR", "city": "Lyon", "email": "carl@leonescars.fr", "payment_method": { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "type": "bank_account", "association_mode": "exclusive" } }`) req, err := http.NewRequest("POST", "https://api.invunion.com/api/v1/counterparties", bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") 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", { method: "POST", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ "name_original": "Leones Cars", "name_display": "Leones Cars", "category": "professional", "payment_terms_days": 30, "is_client": true, "is_payer": true, "external_reference": "ERP-1842", "vat_number": "FR12345678901", "country": "FR", "city": "Lyon", "email": "carl@leonescars.fr", "payment_method": { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "type": "bank_account", "association_mode": "exclusive" } }), }); console.log(await response.json()); ``` ## Success (201) ```json { "success": true, "data": { "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" }, "_payment_method_resolution": { "status": "created", "paymentMethodId": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "associationMode": "exclusive" } }, "message": "Counterparty created successfully" } ```