{
  "openapi": "3.1.0",
  "info": {
    "title": "filings.fr · French company data API",
    "version": "1.0.0",
    "description": "REST API over the French company register: identity, directors, beneficial owners, annual accounts, documents and legal notices.",
    "termsOfService": "https://filings.fr/cgu",
    "contact": {
      "name": "filings",
      "url": "https://filings.fr/contact"
    },
    "license": {
      "name": "Commercial · see plan terms",
      "url": "https://filings.fr/precios"
    }
  },
  "servers": [
    {
      "url": "https://api.filings.fr",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Documentation",
    "url": "https://filings.fr/developers"
  },
  "tags": [
    {
      "name": "Companies",
      "description": "Company profile · Directors and representatives · Financial data · Beneficial owners · Official documents · Legal notices · Establishments"
    },
    {
      "name": "Search",
      "description": "Search companies"
    },
    {
      "name": "Directors",
      "description": "Director profile"
    }
  ],
  "paths": {
    "/api/public/v1/company/{siren}": {
      "get": {
        "operationId": "company",
        "summary": "Company profile",
        "description": "Every data point on a company, by SIREN: identity, legal form, share capital, registered office, NAF code, status and directors.",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number (9 digits).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/directors": {
      "get": {
        "operationId": "company-directors",
        "summary": "Directors and representatives",
        "description": "List of directors (individuals and legal entities) with role and dates.",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number (9 digits).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/financials": {
      "get": {
        "operationId": "company-financials",
        "summary": "Financial data",
        "description": "Annual accounts: revenue, net income, headcount and balance sheets (INPI).",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/beneficiaries": {
      "get": {
        "operationId": "company-beneficiaries",
        "summary": "Beneficial owners",
        "description": "Beneficial owners (RBE register): identities and ownership percentages.",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/documents": {
      "get": {
        "operationId": "company-documents",
        "summary": "Official documents",
        "description": "Articles of association, deeds and accounts filed with the registry (INPI).",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/announcements": {
      "get": {
        "operationId": "company-announcements",
        "summary": "Legal notices",
        "description": "BODACC filings and legal notices published by the company.",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/company/{siren}/establishments": {
      "get": {
        "operationId": "company-establishments",
        "summary": "Establishments",
        "description": "List of the company's establishments (SIRET).",
        "tags": [
          "Companies"
        ],
        "parameters": [
          {
            "name": "siren",
            "in": "path",
            "required": true,
            "description": "SIREN number.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Search companies",
        "description": "Search by company name, SIREN or director.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search term.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, from 1.",
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    },
    "/api/public/v1/director/{personId}": {
      "get": {
        "operationId": "director",
        "summary": "Director profile",
        "description": "Every mandate held by a person (person_id), with the related companies.",
        "tags": [
          "Directors"
        ],
        "parameters": [
          {
            "name": "personId",
            "in": "path",
            "required": true,
            "description": "person_id identifier (UUID returned by search).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Monthly call quota exhausted"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "apikey"
      }
    }
  },
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "ApiKeyQuery": []
    }
  ]
}