{"openapi":"3.1.0","info":{"title":"Company France API","version":"1.0.0","description":"Public API for French company data (SIRENE/INSEE + RNE/INPI). Enrich your app with legal units, establishments, directors and annual accounts. Authenticate every request with your API key pair.","contact":{"name":"Company France","url":"https://companyfrance.fr"}},"servers":[{"url":"https://companyfrance.fr/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"tags":[{"name":"Search","description":"Find companies"},{"name":"Legal units","description":"Unité légale (SIREN)"},{"name":"Establishments","description":"Établissement (SIRET)"},{"name":"Reference","description":"NAF & legal-form nomenclatures"},{"name":"Account","description":"Your plan & usage"}],"paths":{"/search":{"get":{"tags":["Search"],"summary":"Search legal units","description":"DB-backed search. Provide at least one filter.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Free text (name / director / SIREN prefix)"},{"name":"naf","in":"query","schema":{"type":"string"},"description":"NAF/APE code or division prefix"},{"name":"categorieJuridique","in":"query","schema":{"type":"string"}},{"name":"etat","in":"query","schema":{"type":"string","enum":["A","C"]}},{"name":"codePostal","in":"query","schema":{"type":"string"}},{"name":"commune","in":"query","schema":{"type":"string"}},{"name":"departement","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search/dirigeants":{"get":{"tags":["Search"],"summary":"Search companies by director","description":"Reverse director lookup: every company a person is/was a director of (RNE directors + sole traders). Accent- and case-insensitive. Provide at least one of nom/prenom (min 2 chars).","parameters":[{"name":"nom","in":"query","schema":{"type":"string"},"description":"Surname or any name token"},{"name":"prenom","in":"query","schema":{"type":"string"},"description":"Given name(s)"},{"name":"strict","in":"query","schema":{"type":"boolean","default":false},"description":"Field-locked matching (fewer homonyms)"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Companies linked to the person","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirigeantSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search/adresse":{"get":{"tags":["Search"],"summary":"Search companies by address","description":"Reverse address lookup: every company registered at an address, grouped by SIREN (siège first). The postal code is required — refine with voie (street) and commune.","parameters":[{"name":"codePostal","in":"query","required":true,"schema":{"type":"string"},"description":"Postal code (5 digits, or ≥ 4-digit prefix) — required anchor"},{"name":"voie","in":"query","schema":{"type":"string"},"description":"Street tokens (numéro / type / libellé)"},{"name":"commune","in":"query","schema":{"type":"string"},"description":"Commune name (refinement)"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Companies registered at the address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/unite-legale/{siren}":{"get":{"tags":["Legal units"],"summary":"Get a legal unit","description":"The `capital` block is financial data: returned only on the Pro/Enterprise plans (null otherwise).","parameters":[{"name":"siren","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{9}$"}}],"responses":{"200":{"description":"Legal unit","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/UniteLegaleDetail"},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/unite-legale/{siren}/etablissements":{"get":{"tags":["Legal units"],"summary":"List a legal unit’s establishments","parameters":[{"name":"siren","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{9}$"}},{"name":"etat","in":"query","schema":{"type":"string","enum":["A","F"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Paginated establishments"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/unite-legale/{siren}/dirigeants":{"get":{"tags":["Legal units"],"summary":"List a legal unit’s directors","parameters":[{"name":"siren","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{9}$"}}],"responses":{"200":{"description":"Directors"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/unite-legale/{siren}/finances":{"get":{"tags":["Legal units"],"summary":"Annual accounts (Pro/Enterprise)","description":"Plan-gated: requires the Pro or Enterprise plan.","parameters":[{"name":"siren","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{9}$"}}],"responses":{"200":{"description":"Annual accounts"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/etablissement/{siret}":{"get":{"tags":["Establishments"],"summary":"Get an establishment","parameters":[{"name":"siret","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{14}$"}}],"responses":{"200":{"description":"Establishment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Etablissement"},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/naf":{"get":{"tags":["Reference"],"summary":"NAF nomenclature","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"NAF codes"}}}},"/naf/{code}":{"get":{"tags":["Reference"],"summary":"Resolve a NAF code","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Label"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/categories-juridiques":{"get":{"tags":["Reference"],"summary":"Legal-form nomenclature","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Legal forms"}}}},"/me":{"get":{"tags":["Account"],"summary":"Your plan & usage","responses":{"200":{"description":"Plan + usage"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Public key (pk_live_…)"},"ApiSecretAuth":{"type":"apiKey","in":"header","name":"X-API-Secret","description":"Secret key (sk_live_…)"}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing/invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Quota or rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"code":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasNext":{"type":"boolean"}}},"UniteLegaleSummary":{"type":"object","properties":{"siren":{"type":"string"},"sirenFormatted":{"type":"string"},"name":{"type":"string"},"sigle":{"type":"string","nullable":true},"legalForm":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"label":{"type":"string","nullable":true}}},"activity":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"label":{"type":"string","nullable":true}}},"category":{"type":"string","nullable":true},"active":{"type":"boolean"},"state":{"type":"string","nullable":true},"dateCreation":{"type":"string","format":"date-time","nullable":true}}},"UniteLegaleDetail":{"allOf":[{"$ref":"#/components/schemas/UniteLegaleSummary"},{"type":"object","properties":{"vatNumber":{"type":"string","nullable":true},"denominations":{"type":"object","properties":{"legal":{"type":"string","nullable":true},"usual":{"type":"array","items":{"type":"string"}},"sigle":{"type":"string","nullable":true}}},"workforceRange":{"type":"string","nullable":true},"employer":{"type":"boolean","nullable":true},"capital":{"type":"object","nullable":true,"description":"Financial data — Pro/Enterprise only (null on Free/Starter).","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"variable":{"type":"boolean"}}},"establishments":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"}}}}}]},"Etablissement":{"type":"object","properties":{"siret":{"type":"string"},"siretFormatted":{"type":"string"},"siren":{"type":"string"},"siege":{"type":"boolean"},"active":{"type":"boolean"},"state":{"type":"string","nullable":true},"address":{"type":"object"},"activity":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"label":{"type":"string","nullable":true}}},"enseigne":{"type":"string","nullable":true},"dateCreation":{"type":"string","format":"date-time","nullable":true}}},"SearchResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UniteLegaleSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]},"PersonCompany":{"type":"object","description":"A company a searched person is/was a director of.","properties":{"siren":{"type":"string"},"sirenFormatted":{"type":"string"},"name":{"type":"string"},"activity":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"label":{"type":"string","nullable":true}}},"active":{"type":"boolean"},"state":{"type":"string","nullable":true},"dateCreation":{"type":"string","format":"date-time","nullable":true},"dateRadiation":{"type":"string","format":"date-time","nullable":true},"roles":{"type":"array","items":{"type":"string"},"description":"Role labels (Président, Gérant, Entrepreneur individuel…)"},"matched":{"type":"string","description":"The director name that matched the query"}}},"AddressCompany":{"type":"object","description":"A company registered at the searched address.","properties":{"siren":{"type":"string"},"sirenFormatted":{"type":"string"},"name":{"type":"string"},"activity":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"label":{"type":"string","nullable":true}}},"active":{"type":"boolean"},"state":{"type":"string","nullable":true},"dateCreation":{"type":"string","format":"date-time","nullable":true},"address":{"type":"string","description":"Best matched establishment address (siège preferred)"},"street":{"type":"string"},"postalCode":{"type":"string"},"commune":{"type":"string"},"headOffice":{"type":"boolean","description":"At least one matched establishment is the registered office"},"establishmentsMatched":{"type":"integer"}}},"DirigeantSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PersonCompany"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"totalMatched":{"type":"integer","description":"Distinct companies matched before the display cap"},"capped":{"type":"boolean","description":"True when results were truncated — narrow the query"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]},"AddressSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AddressCompany"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"totalMatched":{"type":"integer","description":"Distinct companies matched before the display cap"},"capped":{"type":"boolean","description":"True when results were truncated — add a voie to refine"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}}