API v1 · OpenAPI 3.1 · stable

API Reference

Query French company data (SIRENE/INSEE + RNE/INPI) from your app: search, legal units, establishments, directors and annual accounts. A single base URL, authentication with a key pair.

Overview

A stateless REST API, JSON in/out, versioned. Every route is prefixed with /v1 and returns the { success, data, timestamp } envelope.

Base URLhttps://companyfrance.fr/api/v1
Versionv1 · OpenAPI 3.1
Formatapplication/json
AuthenticationX-API-Key + X-API-Secret

Data sourced from SIRENE/INSEE (open data) enriched with RNE/INPI. The full contract is available as OpenAPI 3.1.

Authentication

Every request must include your API key pair in the HTTP headers. The public key identifies your account; the secret key authenticates it. Never expose your secret key in the browser.

curl "https://companyfrance.fr/api/v1/me" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Required headers

X-API-Key — public key, format pk_live_…
X-API-Secret — secret key, format sk_live_… (keep server-side)

Create and revoke your keys from /dashboard/api/keys.

Error format

Every error returns a 4xx or 5xx HTTP status and a JSON body with success: false, an error field (human-readable) and a code field (machine identifier).

application/json

{
  "success": false,
  "error": "No legal unit found for this SIREN.",
  "code": "NOT_FOUND",
  "timestamp": "2026-06-22T10:00:00.000Z"
}

MISSING_CREDENTIALSAPI keys missing from the headers.
INVALID_API_KEYInvalid public or secret key.
API_KEY_DISABLEDKey disabled or expired.
MISSING_FILTERNo search filter provided (q, naf, codePostal…).
INVALID_SIRENInvalid SIREN: 9 digits expected.
NOT_FOUNDResource not found.
INTERNAL_ERRORInternal server error.

Pagination

List endpoints accept page (default 1) and perPage (default 20, max 100). The response includes a pagination object describing the current page and whether a next page exists.

application/json

"pagination": {
  "page": 1,
  "perPage": 20,
  "total": 137,
  "totalPages": 7,
  "hasNext": true
}

Quotas & limits

Calls count against your plan's monthly quota and are rate-limited per hour. Every response exposes your usage through X-RateLimit-* headers.

Plan monthly quotaX-RateLimit-Limit
Calls remaining in the periodX-RateLimit-Remaining
Reset timestamp (epoch)X-RateLimit-Reset

Exceeding the limit

Beyond the quota or hourly limit, the API returns 429. An inactive subscription returns 402. Watch your X-RateLimit-Remaining header to anticipate.

Search legal units

GET/v1/search

Database-backed search over French companies. Provide at least one filter. Results are paginated and sorted by name.

Query parameters

qstringoptional
Free text: name, director name, or SIREN prefix. A 9-digit q performs an exact SIREN lookup.
nafstringoptional
Exact NAF/APE code (e.g. 29.10Z) or division prefix (e.g. 62).
categorieJuridiquestringoptional
INSEE legal-form code (e.g. 5710).
etatstringoptional
AC
Administrative state: A (active) or C (ceased).
codePostalstringoptional
Exact postal code (matches an establishment).
communestringoptional
Commune name (partial match).
departementstringoptional
2-digit department (postal-code prefix).
pageintegeroptionaldefault 1
Page number (starting at 1).
perPageintegeroptionaldefault 20
Results per page (max 100).

Responses

200Paginated results (items + pagination).
400No filter provided.
401API keys missing or invalid.
429Quota or rate limit exceeded.

cURL

curl "https://companyfrance.fr/api/v1/search?q=renault&departement=92&perPage=20" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "sigle": null,
        "legalForm": { "code": "5710", "label": "SA à conseil d'administration" },
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "category": "GE",
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "totalPages": 1, "hasNext": false }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Search companies by director

GET/v1/search/dirigeants

Reverse lookup: every company a person directs or has directed (RNE directors + sole traders). Case- and accent-insensitive. Provide at least nom or prenom (min 2 characters).

Query parameters

nomstringoptional
Surname (or any name token).
prenomstringoptional
Given name(s).
strictbooleanoptionaldefault false
true → field-locked matching (nom↔nom, prénom↔prénom): fewer homonyms.
pageintegeroptionaldefault 1
Page number (starting at 1).
perPageintegeroptionaldefault 20
Results per page (max 100).

Responses

200Companies linked to the person (items + pagination, totalMatched, capped).
400No director name provided.
401API keys missing or invalid.
429Quota or rate limit exceeded.

cURL

curl "https://companyfrance.fr/api/v1/search/dirigeants?nom=Dupont&prenom=Jean" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z",
        "dateRadiation": null,
        "roles": ["Président du conseil d'administration"],
        "matched": "Jean Dupont"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "totalPages": 1, "hasNext": false },
    "totalMatched": 3,
    "capped": false
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Search companies by address

GET/v1/search/adresse

Reverse lookup: every company registered at an address, grouped by SIREN (head office first). The postal code is required; refine with street and commune.

Query parameters

codePostalstringrequired
Postal code — required. 5 digits (or a ≥4-digit prefix). It's the indexed anchor.
voiestringoptional
Street tokens (number / type / name), in any order.
communestringoptional
Commune name (optional refinement).
pageintegeroptionaldefault 1
Page number (starting at 1).
perPageintegeroptionaldefault 20
Results per page (max 100).

Responses

200Companies at the address (items + pagination, totalMatched, capped).
400Postal code missing.
401API keys missing or invalid.
429Quota or rate limit exceeded.

cURL

curl "https://companyfrance.fr/api/v1/search/adresse?codePostal=92100&voie=Quai+Le+Gallo" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z",
        "address": "13 Quai Alphonse Le Gallo, 92100 Boulogne-Billancourt",
        "street": "13 Quai Alphonse Le Gallo",
        "postalCode": "92100",
        "commune": "Boulogne-Billancourt",
        "headOffice": true,
        "establishmentsMatched": 1
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 12, "totalPages": 1, "hasNext": false },
    "totalMatched": 12,
    "capped": false
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Get a legal unit

GET/v1/unite-legale/{siren}

Full company record: names, legal form, activity, capital (Pro/Enterprise), workforce, VAT number and establishment counts.

Path parameters

sirenstringrequired
Legal unit SIREN — 9 digits.

Responses

200Legal unit record.
404Resource not found.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "sirenFormatted": "552 032 534",
    "name": "RENAULT",
    "legalForm": { "code": "5710", "label": "SA à conseil d'administration" },
    "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
    "active": true,
    "state": "A",
    "vatNumber": "FR41552032534",
    "workforceRange": "53",
    "capital": { "amount": 1126701902, "currency": "EUR", "variable": false },
    "establishments": { "total": 12, "active": 9 }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

List a legal unit's establishments

GET/v1/unite-legale/{siren}/etablissements

Establishments (SIRET) attached to a SIREN, paginated. Filter on state to keep only active establishments.

Path parameters

sirenstringrequired
Legal unit SIREN — 9 digits.

Query parameters

etatstringoptional
AF
Establishment state: A (active) or F (closed).
pageintegeroptionaldefault 1
Page number (starting at 1).
perPageintegeroptionaldefault 20
Results per page (max 100).

Responses

200Paginated establishments.
404Resource not found.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/etablissements?etat=A" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

List a legal unit's directors

GET/v1/unite-legale/{siren}/dirigeants

Directors (manager, chairman…) sourced from the RNE. For a sole trader, the individual is synthesised from the legal-unit identity.

Path parameters

sirenstringrequired
Legal unit SIREN — 9 digits.

Responses

200List of directors (count + items).
404Resource not found.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/dirigeants" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "count": 1,
    "items": [
      {
        "type": "person",
        "name": "Jean Dupont",
        "nom": "Dupont",
        "prenoms": "Jean",
        "denomination": null,
        "role": "Président du conseil d'administration",
        "birthYear": 1968
      }
    ]
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Legal unit annual accounts

GET/v1/unite-legale/{siren}/finances

Filed annual accounts (revenue, net income…) when available.

Path parameters

sirenstringrequired
Legal unit SIREN — 9 digits.

Responses

200Annual accounts.
403Insufficient plan — upgrade required.
404Resource not found.

Endpoint reserved for Pro and Enterprise plans

Access to annual accounts requires a Pro or Enterprise subscription. On a lower plan, the API returns 403.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/finances" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "count": 1,
    "items": [
      {
        "year": 2024,
        "dateCloture": "2024-12-31",
        "typeBilan": "C",
        "totalBilan": 98765432000,
        "capitauxPropres": 31200000000,
        "resultatNet": 752000000,
        "chiffreAffaires": 56601000000,
        "currency": "EUR",
        "confidential": false,
        "dateDepot": "2025-05-14"
      }
    ]
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Get an establishment

GET/v1/etablissement/{siret}

Establishment record by SIRET: address, activity, sign, head-office flag and administrative state.

Path parameters

siretstringrequired
Establishment SIRET — 14 digits.

Responses

200Establishment record.
404Resource not found.

cURL

curl "https://companyfrance.fr/api/v1/etablissement/55203253400041" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

NAF nomenclature

GET/v1/naf

List of NAF/APE codes with their labels. Filter with q to search by label or code.

Query parameters

qstringoptional
Search by label or NAF code.

Responses

200NAF codes.

cURL

curl "https://companyfrance.fr/api/v1/naf?q=automobile" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Resolve a NAF code

GET/v1/naf/{code}

Returns the label for a specific NAF/APE code.

Path parameters

codestringrequired
NAF/APE code to resolve (e.g. 29.10Z).

Responses

200Code label.
404Resource not found.

cURL

curl "https://companyfrance.fr/api/v1/naf/29.10Z" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Legal-form nomenclature

GET/v1/categories-juridiques

List of legal-form (INSEE) codes with their labels. Filter with q.

Query parameters

qstringoptional
Search by label or code.

Responses

200Legal forms.

cURL

curl "https://companyfrance.fr/api/v1/categories-juridiques?q=SARL" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Your plan & usage

GET/v1/me

Returns the calling account, its plan and current usage. This call itself counts against the quota.

Responses

200Plan + usage.
400API key not attached to a company.

cURL

curl "https://companyfrance.fr/api/v1/me" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "keyId": "key_01J…",
    "company": { "id": "cmp_01J…" },
    "plan": {
      "code": "pro",
      "name": "Pro",
      "status": "active",
      "trialEndsAt": null,
      "currentPeriodEnd": "2027-06-22T00:00:00.000Z"
    },
    "usage": {
      "used": 1284,
      "limit": 50000,
      "remaining": 48716,
      "percentage": 3,
      "resetAt": "2026-07-01T00:00:00.000Z",
      "hourlyRateLimit": 1000
    }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}