CompanyFrance
Zurück zur Doku
PlaygroundGET /api/v1/openapi

API v1 · OpenAPI 3.1 · stabil

API-Referenz

Fragen Sie französische Unternehmensdaten (SIRENE/INSEE + RNE/INPI) aus Ihrer Anwendung ab: Suche, Rechtseinheiten, Niederlassungen, Geschäftsführer und Jahresabschlüsse. Eine einzige Basis-URL, Authentifizierung mit einem Schlüsselpaar.

Überblick

Eine zustandslose REST-API, JSON ein/aus, versioniert. Jede Route hat das Präfix /v1 und gibt die Hülle { success, data, timestamp } zurück.

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

Daten aus SIRENE/INSEE (Open Data), angereichert mit RNE/INPI. Der vollständige Vertrag ist als OpenAPI 3.1 verfügbar.

Authentifizierung

Jede Anfrage muss Ihr API-Schlüsselpaar in den HTTP-Headern enthalten. Der öffentliche Schlüssel identifiziert Ihr Konto; der geheime Schlüssel authentifiziert es. Geben Sie Ihren geheimen Schlüssel niemals im Browser preis.

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

Erforderliche Header

  • X-API-Key — öffentlicher Schlüssel, Format pk_live_…
  • X-API-Secret — geheimer Schlüssel, Format sk_live_… (serverseitig aufbewahren)

Erstellen und widerrufen Sie Ihre Schlüssel unter /dashboard/api/keys.

Fehlerformat

Jeder Fehler gibt einen HTTP-Status 4xx oder 5xx und einen JSON-Body mit success: false, einem error-Feld (lesbar) und einem code-Feld (Maschinenkennung) zurück.

application/json
{
  "success": false,
  "error": "No legal unit found for this SIREN.",
  "code": "NOT_FOUND",
  "timestamp": "2026-06-22T10:00:00.000Z"
}
  • MISSING_CREDENTIALSAPI-Schlüssel fehlen in den Headern.
  • INVALID_API_KEYUngültiger öffentlicher oder geheimer Schlüssel.
  • API_KEY_DISABLEDSchlüssel deaktiviert oder abgelaufen.
  • MISSING_FILTERKein Suchfilter angegeben (q, naf, codePostal…).
  • INVALID_SIRENUngültige SIREN: 9 Ziffern erwartet.
  • NOT_FOUNDRessource nicht gefunden.
  • INTERNAL_ERRORInterner Serverfehler.

Paginierung

Listen-Endpunkte akzeptieren page (Standard 1) und perPage (Standard 20, max. 100). Die Antwort enthält ein pagination-Objekt, das die aktuelle Seite und das Vorhandensein einer nächsten Seite beschreibt.

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

Kontingente & Limits

Aufrufe werden auf das monatliche Kontingent Ihres Tarifs angerechnet und pro Stunde begrenzt. Jede Antwort zeigt Ihren Verbrauch über X-RateLimit-*-Header.

  • Monatliches Kontingent des TarifsX-RateLimit-Limit
  • Verbleibende Aufrufe im ZeitraumX-RateLimit-Remaining
  • Reset-Zeitstempel (Epoch)X-RateLimit-Reset

Überschreitung

Über das Kontingent oder das Stundenlimit hinaus gibt die API 429 zurück. Ein inaktives Abonnement gibt 402 zurück. Beobachten Sie Ihren X-RateLimit-Remaining-Header, um vorzubeugen.

Unternehmen nach Geschäftsführer suchen

GET/v1/search/dirigeants

Umgekehrte Suche: alle Unternehmen, die eine Person leitet oder geleitet hat (RNE-Geschäftsführer + Einzelunternehmer). Groß-/Kleinschreibung- und akzentunabhängig. Geben Sie mindestens nom oder prenom an (min. 2 Zeichen).

Query-Parameter

  • nomstringoptional

    Nachname (oder ein beliebiger Namensteil).

  • prenomstringoptional

    Vorname(n).

  • strictbooleanoptionalStandard false

    true → feldgebundener Abgleich (nom↔nom, prénom↔prénom): weniger Namensvetter.

  • pageintegeroptionalStandard 1

    Seitennummer (ab 1).

  • perPageintegeroptionalStandard 20

    Ergebnisse pro Seite (max. 100).

Antworten

  • 200Mit der Person verknüpfte Unternehmen (items + pagination, totalMatched, capped).
  • 400Kein Geschäftsführername angegeben.
  • 401API-Schlüssel fehlen oder ungültig.
  • 429Kontingent oder Ratenlimit überschritten.
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"
}

Unternehmen nach Adresse suchen

GET/v1/search/adresse

Umgekehrte Suche: alle an einer Adresse registrierten Unternehmen, gruppiert nach SIREN (Hauptsitz zuerst). Die Postleitzahl ist erforderlich; verfeinern Sie mit Straße und Gemeinde.

Query-Parameter

  • codePostalstringerforderlich

    Postleitzahl — erforderlich. 5 Ziffern (oder ein Präfix mit min. 4 Ziffern). Sie ist der indizierte Anker.

  • voiestringoptional

    Straßenbegriffe (Nummer / Typ / Name), in beliebiger Reihenfolge.

  • communestringoptional

    Gemeindename (optionale Verfeinerung).

  • pageintegeroptionalStandard 1

    Seitennummer (ab 1).

  • perPageintegeroptionalStandard 20

    Ergebnisse pro Seite (max. 100).

Antworten

  • 200Unternehmen an der Adresse (items + pagination, totalMatched, capped).
  • 400Postleitzahl fehlt.
  • 401API-Schlüssel fehlen oder ungültig.
  • 429Kontingent oder Ratenlimit überschritten.
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"
}

Eine Rechtseinheit abrufen

GET/v1/unite-legale/{siren}

Vollständiger Unternehmensdatensatz: Namen, Rechtsform, Tätigkeit, Kapital (Pro/Enterprise), Belegschaft, USt-IdNr. und Anzahl der Niederlassungen.

Pfadparameter

  • sirenstringerforderlich

    SIREN der Rechtseinheit — 9 Ziffern.

Antworten

  • 200Datensatz der Rechtseinheit.
  • 404Ressource nicht gefunden.
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"
}

Niederlassungen einer Rechtseinheit auflisten

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

Niederlassungen (SIRET), die einer SIREN zugeordnet sind, paginiert. Filtern Sie nach Status, um nur aktive Niederlassungen zu behalten.

Pfadparameter

  • sirenstringerforderlich

    SIREN der Rechtseinheit — 9 Ziffern.

Query-Parameter

  • etatstringoptional
    AF

    Niederlassungsstatus: A (aktiv) oder F (geschlossen).

  • pageintegeroptionalStandard 1

    Seitennummer (ab 1).

  • perPageintegeroptionalStandard 20

    Ergebnisse pro Seite (max. 100).

Antworten

  • 200Paginierte Niederlassungen.
  • 404Ressource nicht gefunden.
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_..."

Geschäftsführer einer Rechtseinheit auflisten

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

Geschäftsführer (Geschäftsführer, Präsident…) aus dem RNE. Für einen Einzelunternehmer wird die natürliche Person aus der Identität der Rechtseinheit abgeleitet.

Pfadparameter

  • sirenstringerforderlich

    SIREN der Rechtseinheit — 9 Ziffern.

Antworten

  • 200Liste der Geschäftsführer (count + items).
  • 404Ressource nicht gefunden.
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"
}

Jahresabschlüsse einer Rechtseinheit

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

Hinterlegte Jahresabschlüsse (Umsatz, Jahresüberschuss…), sofern verfügbar.

Pfadparameter

  • sirenstringerforderlich

    SIREN der Rechtseinheit — 9 Ziffern.

Antworten

  • 200Jahresabschlüsse.
  • 403Unzureichender Tarif — Upgrade erforderlich.
  • 404Ressource nicht gefunden.

Endpunkt nur für Pro- und Enterprise-Tarife

Der Zugriff auf Jahresabschlüsse erfordert ein Pro- oder Enterprise-Abonnement. Bei einem niedrigeren Tarif gibt die API 403 zurück.
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"
}

Eine Niederlassung abrufen

GET/v1/etablissement/{siret}

Niederlassungsdatensatz per SIRET: Adresse, Tätigkeit, Geschäftsname, Hauptsitz-Kennzeichen und Verwaltungsstatus.

Pfadparameter

  • siretstringerforderlich

    SIRET der Niederlassung — 14 Ziffern.

Antworten

  • 200Datensatz der Niederlassung.
  • 404Ressource nicht gefunden.
cURL
curl "https://companyfrance.fr/api/v1/etablissement/55203253400041" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

NAF-Nomenklatur

GET/v1/naf

Liste der NAF/APE-Codes mit ihren Bezeichnungen. Filtern Sie mit q, um nach Bezeichnung oder Code zu suchen.

Query-Parameter

  • qstringoptional

    Suche nach Bezeichnung oder NAF-Code.

Antworten

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

Einen NAF-Code auflösen

GET/v1/naf/{code}

Gibt die Bezeichnung eines bestimmten NAF/APE-Codes zurück.

Pfadparameter

  • codestringerforderlich

    Aufzulösender NAF/APE-Code (z. B. 29.10Z).

Antworten

  • 200Code-Bezeichnung.
  • 404Ressource nicht gefunden.
cURL
curl "https://companyfrance.fr/api/v1/naf/29.10Z" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Nomenklatur der Rechtsformen

GET/v1/categories-juridiques

Liste der Rechtsformcodes (INSEE) mit ihren Bezeichnungen. Filtern Sie mit q.

Query-Parameter

  • qstringoptional

    Suche nach Bezeichnung oder Code.

Antworten

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

Ihr Tarif & Verbrauch

GET/v1/me

Gibt das aufrufende Konto, seinen Tarif und den aktuellen Verbrauch zurück. Dieser Aufruf wird selbst auf das Kontingent angerechnet.

Antworten

  • 200Tarif + Verbrauch.
  • 400API-Schlüssel keinem Unternehmen zugeordnet.
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"
}