One GET, one company, one JSON document. Every endpoint needs an API key; the country
comes first in the path, then the identifier its national register uses:
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"
}On these endpoints every code arrives with the scheme that resolves it; on /suggest it
arrives with a label instead. data_updated_at is the register's own timestamp for this
record, not the time it was imported. The full response also carries country_data: the
source's own fields, under their original names.
Four reads
All four are GET, and all of them are country-first.
| Operation | Path |
|---|---|
| Read a legal entity | /v1/{country}/legal-entities/{registry_number} |
| List its establishments | /v1/{country}/legal-entities/{registry_number}/establishments |
| Read one establishment | /v1/{country}/establishments/{establishment_number} |
| Autocomplete on a name or identifier | /v1/{country}/suggest |
Beyond them, POST /v1/{country}/resolve, /enrich and /jobs identify and enrich your
own lists of companies, watchlists follow named companies and deliver what
happens to them by webhook, email or a feed, and segments count the
companies matching explicit filters and export them as a CSV.
The contract itself is published at GET /v1/openapi, and reading it needs no key.
Start here
- Quickstart — a key and a first answer, in about two minutes.
- Conventions — what every endpoint shares: identifiers, nulls and pagination.
- Sources & coverage — which register this comes from, how fresh it is, and what it does not contain.