Create counterparty

POST https://api.invunion.com/api/v1/counterparties counterparties:write Markdown

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.

Body parameters

Name	Type	Required
`name_original` Legal or source name. This is the only required field. Also accepted as name in bulk import. Example: Leones Cars	string Max 255	Required
`name_display` Display name shown in the product. Defaults to empty when omitted. Example: Leones Cars	string Max 255	Optional
`account_code` Your account code. Unique per tenant. If omitted, Invunion assigns CPT-NNN. Example: CPT-042	string Max 50	Recommended
`category` Legal form of the counterparty. Default professional.	string Max 50	Recommended
Allowed values`individualprofessionalgovernmental`
`payment_terms_days` Payment terms in days, 0 to 365. If omitted, tenant default applies. Example: 30	integer	Optional
`is_supplier` Supplier role. Default false. Allowed values`truefalse`	boolean	Optional
`is_client` Client role. Default true on create. Allowed values`truefalse`	boolean	Optional
`is_partner` Partner role. Default false. Allowed values`truefalse`	boolean	Optional
`is_payer` Payer role. Default false. Allowed values`truefalse`	boolean	Optional
`is_internal` Internal entity. Default false. Allowed values`truefalse`	boolean	Optional
`is_employee` Employee. Default false. Allowed values`truefalse`	boolean	Optional
`external_reference` External reference. Your ERP or billing customer id. Used for identity lookup. Example: ERP-1842	string Max 255	Optional
`vat_number` VAT number. Used for identity lookup on import. Example: FR12345678901	string Max 50	Optional
`registration_number` National ID (SIREN, company number, and similar). Example: 123456789	string Max 100	Optional
`electronic_address` E-invoicing address (Peppol and similar). Example: 0208:123456789	string Max 255	Optional
`address` Street address. Example: 12 Grove Street	string No maximum	Optional
`city` City. Example: Lyon	string Max 255	Optional
`postal_code` Postal code. Example: 69001	string Max 20	Optional
`country` Country name or ISO 3166-1 alpha-2 code. Stored as alpha-2. Invalid values return 400 on create. Example: FR	string No maximum	Optional
`email` Contact email. Example: carl@leonescars.fr	string No maximum	Optional
`phone` Phone number. Example: +33472000000	string Max 50	Optional
`analytic_1` Analytic axis 1. Example: SALES-EU	string Max 100	Optional
`analytic_2` Analytic axis 2. Example: CHANNEL-DIRECT	string Max 100	Optional
`metadata` JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. Example: {"erp_id":"C-1842"}	object	Optional
`createDefaultPaymentMethod` If false, skip the empty Default catalog payment method. Default true. Independent of payment_method. Allowed values`truefalse`	boolean	Optional
`payment_method` 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.	object	Recommended
`name` Instrument display name. Defaults to name_original. Example: Leones Cars EUR	string Max 255	Optional
`iban` IBAN. Required unless identifier is set. Unique per tenant catalog. BIC alone is not enough. Example: FR7630006000011234567890189	string Max 50	Recommended
`identifier` Non-IBAN instrument key (PayPal email, wallet id, terminal number). Required unless iban is set. Unique per tenant catalog. Example: carl@leonescars.fr	string Max 120	Optional
`code` Your payment-method code. Unique per tenant. If omitted, Invunion assigns PM-NNN. Example: PM-001	string Max 50	Recommended
`type` Instrument type. Default bank_account.	string No maximum	Recommended
Allowed values`bank_accountcredit_cardpaypalwerotwintcrypto_walletother`
`bic` BIC. Bank name and country are filled from the BIC directory when omitted. Example: BNPAFRPP	string Max 11	Optional
`currency` ISO 4217 currency code. Default EUR. Example: EUR	string Max 3	Optional
`association_mode` exclusive (one owner) or shared (several counterparties). Default exclusive. Applies only when creating a new catalog instrument; an existing shared IBAN stays shared. Allowed values`exclusiveshared`	string No maximum	Recommended
`account_type` Optional account type label. Example: checking	string No maximum	Optional
`bank_name` Bank name. Filled from BIC when omitted. Example: BNP Paribas	string No maximum	Optional
`bank_country` ISO 3166-1 alpha-2 of the bank, not the counterparty country. Example: FR	string No maximum	Optional
`status` Instrument status. Default active.	string No maximum	Optional
Allowed values`activeinactiveerror`
`metadata` JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. Example: {"erp_pm":"BANK-042"}	object	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: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

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

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"
  }
}'

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())

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

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();

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))
}

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());

201

{
  "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"
}