Quickstart · Firmus docs

This page is the human version. A program starts at GET /v1, which answers what this API is, how to authenticate and every endpoint it serves — with no credential at all:

curl https://api.firmus.sh/v1

1. Get a key

Every endpoint under /v1 requires one. Create it in the Firmus console. The token is shown once; if it is lost, mint another and revoke the old one.

Keep it out of your shell history:

read -rs FIRMUS_KEY && export FIRMUS_KEY

2. Look up a company

Every endpoint is a single GET against api.firmus.sh. The country comes first in the path, then the identifier the national register uses — for France, the nine-digit SIREN:

# 552032534 is the registry number the served contract uses as its example.
curl -H "Authorization: Bearer $FIRMUS_KEY" \
  https://api.firmus.sh/v1/fr/legal-entities/552032534

{
  "country_code": "fr",
  "registry_number": "552032534",
  "kind": "company",
  "name": "DANONE",
  "legal_form": { "code": "5599", "scheme": "insee_cj_2018" },
  "activity": { "code": "70.10Z", "scheme": "naf2008" },
  "workforce": {
    "range_code": "42",
    "scheme": "insee_tranche_effectifs",
    "year": 2023
  },
  "size_category": {
    "code": "GE",
    "scheme": "insee_categorie_entreprise",
    "year": 2023
  },
  "status": "active",
  "registered_on": "1955-01-01",
  "ceased_on": null,
  "registered_address": {
    "line": "59 RUE LA FAYETTE",
    "postal_code": "75009",
    "city": "PARIS"
  },
  "partially_disclosed": false,
  "data_updated_at": "2026-04-10T11:28:37Z"
}

Three things in that response are worth knowing before you write code against it, and conventions covers each in full:

legal_form and activity are a code with the scheme that resolves it. The two always travel together.
data_updated_at is the register's timestamp for this record, not the time it was imported.
partially_disclosed marks a record the register publishes in reduced form. It is false here; when it is true, fields are missing by law — see masked records.

The full response also carries country_data, the source's own fields under their original names.

3. List its establishments

A legal entity is the registered company; an establishment is one of its physical sites. The head office comes first, then the rest by number:

curl -sH "Authorization: Bearer $FIRMUS_KEY" \
  https://api.firmus.sh/v1/fr/legal-entities/552032534/establishments \
  | jq '{ count: .pagination.total_count,
          sites: [.establishments[] | { establishment_number, head_office }] }'

{
  "count": 3,
  "sites": [
    { "establishment_number": "55203253400703", "head_office": true },
    { "establishment_number": "55203253400679", "head_office": false },
    { "establishment_number": "55203253400711", "head_office": false }
  ]
}

Closed establishments are left out unless you ask for them with include_closed=true. The list is paginated with page and per_page; both are clamped rather than rejected, so per_page=1000 returns 100 results and not an error.

Authentication — the two ways a key travels, scopes, revocation, and the contract at GET /v1/openapi.
Conventions — identifiers, nulls and pagination.
Errors — the one error shape, and every code a client can meet.
Sources & coverage — where this comes from and how often it moves.

1. Get a key

2. Look up a company

3. List its establishments

Next