Skip to content
Documentation
Guide API Demo
English
Open the app

Create a company

Step-by-step use case to create an accounting company through the API, with its chart of accounts, its journals, its fiscal year and its bank accounts.

Updated on 10/05/2026 Edit this page

This guide creates a Belgian company ready to receive entries. In a single call, NovaFisko installs the country's chart of accounts, the journals, the VAT codes, the fiscal year and its periods.

Prerequisites: a session token or an integration token with the read and write abilities, held by an administrator or a manager of the firm.

Step 1: identify the firm

The firm's public_token is in the response of auth/me.

curl https://api.novafisko.com/v1/auth/me \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "id": 12,
  "name": "Claire Dumont",
  "email": "claire.dumont@fiduciaire-exemple.be",
  "locale": "fr",
  "is_platform_admin": false,
  "is_demo": false,
  "firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple", "role": "admin"}],
  "managed_firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"}]
}

You can only create a company in a firm listed in managed_firms. If the user manages only one, the firm field of step 3 becomes optional.

Step 2 (optional): prefill from the enterprise number

Company detection queries CompanySearch for Belgium and France. It saves you from entering the address and the legal form.

curl "https://api.novafisko.com/v1/lookup/search?q=0999.900.134&country=BE" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Copy the identity fields of the returned sheet into the body of step 3. The available country packs are listed by GET /v1/country-packs and the legal forms by GET /v1/reference/legal-forms.

Step 3: create the company

curl -X POST https://api.novafisko.com/v1/companies \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "firm": "Fd7hQ2mN8sXa",
    "country_pack": "BE",
    "code": "ATELIER",
    "name": "Atelier du Vélo SRL",
    "enterprise_number": "0999.900.134",
    "vat_number": "BE0999900134",
    "legal_form": "SRL",
    "street": "Rue des Carmes",
    "house_number": "18",
    "postal_code": "5000",
    "city": "Namur",
    "country": "BE",
    "vat_regime": "quarterly",
    "locale": "fr",
    "fiscal_year": {"code": "2026", "starts_on": "2026-01-01", "ends_on": "2026-12-31"},
    "banks": [
      {"code": "BNK1", "label": "Compte à vue Belfius", "iban": "BE68539007547034"}
    ]
  }'

Main fields

Field Required Description
name yes Company name, 200 characters max
firm no public_token of the managing firm (12 characters)
country_pack no BE by default. Determines the chart of accounts, VAT and the checks
code no Short code of the company, 20 characters max, letters, digits, hyphens. Converted to upper case
enterprise_number no Checked according to the country (modulo 97 for Belgium)
vat_number no Format and check digits verified according to the country
legal_form, legal_form_code no Free label or code from the reference list
street, house_number, box, postal_code, city, country no Structured address
vat_regime no monthly, quarterly, franchise, exempt or unit depending on the pack
locale no fr, nl, en or de. By default, the user's language
fiscal_year no If present, starts_on and ends_on are required. Otherwise the current calendar year is created
banks no One financial journal per account: code (6 characters max), label, iban

Response 201

{
  "id": 318,
  "public_token": "Av4eLo7Nm2Sr",
  "firm_id": 4,
  "code": "ATELIER",
  "name": "Atelier du Vélo SRL",
  "legal_form": "SRL",
  "enterprise_number": "0999.900.134",
  "vat_number": "BE0999900134",
  "address": "Rue des Carmes 18, 5000 Namur",
  "street": "Rue des Carmes",
  "house_number": "18",
  "postal_code": "5000",
  "city": "Namur",
  "country": "BE",
  "country_pack": "BE",
  "vat_regime": "quarterly",
  "currency": "EUR",
  "locale": "fr",
  "is_active": true,
  "version": 1,
  "firm": {"id": 4, "public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"},
  "fiscal_years": [
    {
      "id": 702,
      "code": "2026",
      "starts_on": "2026-01-01T00:00:00.000000Z",
      "ends_on": "2026-12-31T00:00:00.000000Z",
      "is_closed": false,
      "periods": [
        {"id": 9001, "number": 1, "label": "01/2026", "starts_on": "2026-01-01T00:00:00.000000Z", "ends_on": "2026-01-31T00:00:00.000000Z", "is_locked": false}
      ]
    }
  ],
  "journals": [
    {"id": 2101, "code": "ACH", "label": "Achats", "type": "purchase", "control_account": {"id": 55090, "number": "440000", "label": "Fournisseurs"}},
    {"id": 2102, "code": "VEN", "label": "Ventes", "type": "sale", "control_account": {"id": 55041, "number": "400000", "label": "Clients"}},
    {"id": 2105, "code": "BNK1", "label": "Compte à vue Belfius", "type": "financial", "iban": "BE68539007547034"}
  ]
}

Keep public_token: it is the identifier of the company in all the following routes. The periods and journals lists are abridged here.

Step 4: check the installation

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/accounts?postable=1 \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/vat-codes \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

These two calls return the chart of accounts and the VAT codes of the company, with the id values you will need to record entries.

Common errors

Status Cause Fix
422, field enterprise_number Enterprise number invalid for the country Check the check digits
422, field vat_number Malformed VAT number Include the country prefix, for example BE0999900134
422, field firm The firm is not managed by the user Use a public_token from managed_firms
422, code company_limit_reached Company cap of the licence reached See Check the licence
403, code token_ability_missing Token without the write ability Create a suitable token
Note

Without a firm (firm absent and no managed firm), the company is created as a standalone company and the user becomes its owner. This case concerns self-employed people who keep their own accounts.

Tip

Sending an X-Client-Mutation-Id is pointless here: the POST /v1/companies route is not attached to an existing company. To avoid a duplicate after a network drop, read GET /v1/companies again and look for your code before retrying.

See also