Bulk import counterparties

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

Import counterparties in bulk.

Creates up to 500 counterparties in one request. Each row needs name_original (or name). If identity lookup finds an existing counterparty, the row is skipped: no update, no extra payment method. Nested payment_method with iban or identifier creates a catalog instrument on a new counterparty. Invalid association_mode skips the catalog instrument and keeps the tiers. Invalid country on a row is stored as empty rather than failing the batch.

Body parameters

Name	Type	Required
`counterparties` Rows to import. Maximum 500. Each object accepts the same identity fields as create, plus optional nested payment_method.	array	Required
`name_original` Required on each row. name is accepted as an alias. 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
`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.
`Tenant ID required`	400	The authenticated credential is not bound to a tenant.
`counterparties must be a non-empty array`	400	The body is missing counterparties, or the array is empty.
`Maximum 500 counterparties per bulk import`	400	The array contains more than 500 rows.
`Internal server error`	500	Unexpected server error. The JSON body includes correlationId. Retry with backoff.

Previous: Create counterparty Next: Update counterparty