Managing customers & suppliers

Companies are the customers, suppliers and beneficiaries of a folder. Invoices and customer/supplier entry lines reference them through CompanyId, so you usually need to find or create the company first.

Find an existing company

Search by VAT number, name, search key or external reference with companies.list:

{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "Filter": { "VatNumber": "BE0478696879" }
}

📘

Use ExternalReference for your own identifiers

Store your system's identifier in the company's ExternalReference field when you create it. You can then filter on it to find the company again reliably.

Create a company

companies.new requires FolderId, SearchKey, Name, IsCustomer, IsSupplier, IsVatLiable, LanguageCode and CountryCode:

{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "SearchKey": "HORUS",
  "Name": "Horus Software",
  "IsCustomer": true,
  "IsSupplier": false,
  "IsVatLiable": true,
  "VatNumber": "BE0478696879",
  "LanguageCode": "FR",
  "CountryCode": "BE",
  "Address": "Quai des Ardennes 9",
  "ZipCode": "4020",
  "Locality": "Liège",
  "CustomerPaymentDelay": "30E",
  "ExternalReference": "CRM-000123",
  "Ibans": [
    { "Iban": "BE72000000001616", "Bic": "BPOTBEB1", "IsDefault": true, "IsDomiciliation": false }
  ]
}

The response contains the new company's Id.

Notes:

• By default, a VAT number already used by another company is refused. Set AllowDuplicateVatNumber: true to allow it deliberately.
• CustomerConcentrationAccount and SupplierConcentrationAccount are optional and let you set the concentration accounts explicitly (e.g. 400000, 440000).

Payment terms format

CustomerPaymentDelay and SupplierPaymentDelay follow the format 999[D|J|M][E|F|e|f]:

D/J stand for days and M for months; E/F mean end of month, e/f start of next month.

Update a company

companies.update follows the partial update rule: send only the fields to change.

{
  "CompanyId": "32ebe925-23cc-4a3e-8b36-8b2b33780fc1",
  "InvoiceEmail": "[email protected]",
  "PhoneNumber": ""
}

Here InvoiceEmail is changed, PhoneNumber is erased (empty string), and every other field is left untouched.

Bank accounts (IBANs)