Auregistre Company API

openapi: 3.2.0
info:
  title: Auregistre Company API
  version: 1.0.0
  summary: What changed in a French company, and when.
  description: 'Most company-data services publish a **state**: the name, address and share capital as of today.

    This API publishes the **history**: every value the French official gazette (BODACC) has recorded for a company,

    with the date it was published and a link to the announcement that published it.


    Four things follow from that one idea: the timeline of a company, its filed annual accounts fiscal year by

    fiscal year, a watch over companies you already track, and the count of insolvency openings over time. There

    is no lookup by name, by director or by place: see the documentation for why there never will be.


    Nothing is inferred, scored or estimated. Every value returned was published by the register on the date shown.


    The gazette has been digitised since 2008. For a company older than that, the earliest value returned

    is the oldest one on record, not the company''s original value.


    No API key and no account are involved. Requests are rate limited by IP.'
  termsOfService: https://auregistre.fr/cgu
  contact:
    name: Auregistre
    url: https://auregistre.fr/api
    email: contact@auregistre.fr
  license:
    name: Licence Ouverte 2.0 (Etalab)
    url: https://www.etalab.gouv.fr/licence-ouverte-open-licence/
servers:
- url: https://auregistre.fr/api
  description: Production
security: []
tags:
- name: Company
  description: 'Read-only access by SIREN. There is deliberately no search endpoint: see the documentation for why.'
paths:
  /company/{siren}/timeline:
    get:
      tags:
      - Company
      operationId: getCompanyTimeline
      summary: Every recorded change for one company
      description: 'Returns one entry per field that has **changed at least once**. A field that has never moved is not a timeline,

        it is a state, and it is omitted.


        Announcements that merely cite the SIREN without describing the company are excluded.

        On large franchised networks this is around 40% of what a naive SIREN search returns.


        Responses are cached at the edge for 24 hours. A cached response does not count against the rate limit.'
      parameters:
      - name: siren
        in: path
        required: true
        description: The nine-digit identifier of a French legal entity. Spaces, dots and dashes are accepted and ignored.
        schema:
          type: string
          pattern: ^[0-9 .-]{9,13}$
        examples:
          doctolib:
            value: '794598813'
            summary: Doctolib
          edf:
            value: '552081317'
            summary: EDF
      - name: If-None-Match
        in: header
        required: false
        description: Send the previous `ETag` to get a 304 when nothing has changed.
        schema:
          type: string
      responses:
        '200':
          description: The company timeline.
          headers:
            ETag:
              description: Weak validator of this representation.
              schema:
                type: string
            Cache-Control:
              description: Shared caches may keep this for 24 hours.
              schema:
                type: string
            Link:
              description: 'RFC 8631 discovery links: `service-desc` points at this document, `service-doc` at the human documentation, `license` at the data licence.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '304':
          description: Your `If-None-Match` matched. No body.
        '400':
          description: The SIREN is not nine digits.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#invalid-siren
                title: Invalid SIREN
                status: 400
                detail: A SIREN is the nine-digit identifier the French business register assigns to a legal entity.
        '404':
          description: No announcement describes this SIREN.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#company-not-found
                title: No timeline available
                status: 404
                detail: No gazette announcement describes SIREN 123456789.
        '405':
          description: This endpoint is read-only.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#method-not-allowed
                title: Method not allowed
                status: 405
                detail: This endpoint is read-only. POST is not supported; use GET.
        '429':
          description: Rate limit exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#rate-limit-exceeded
                title: Too many requests
                status: 429
                detail: This API allows 30 reads per minute per IP address.
          headers:
            Retry-After:
              description: Seconds to wait.
              schema:
                type: integer
            RateLimit-Limit:
              schema:
                type: integer
            RateLimit-Remaining:
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '503':
          description: The upstream source did not answer. This says nothing about whether the company exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#upstream-unavailable
                title: Upstream register unavailable
                status: 503
                detail: The upstream register did not answer in time.
  /company/{siren}/financials:
    get:
      tags:
      - Company
      operationId: getCompanyFinancials
      summary: The filed annual accounts of one company, fiscal year by fiscal year
      description: 'Revenue, gross margin, EBITDA, EBIT, net income and the thirteen ratios the INPI computes from the accounts

        a company files with the French business register, one entry per fiscal year and per perimeter.


        **The two perimeters never add up.** `legal_entity` is the one company registered under this SIREN;

        `group` is the consolidated accounts of its group. A holding can file a revenue of zero beside a group

        revenue in the billions, and reading the wrong one is the single easiest mistake with this data.


        Filings kept confidential are not listed. A fiscal year absent here was not filed, was filed under

        confidentiality, or has not been processed by the INPI yet. At most twenty filings are read, most recent first.


        Source: the open dataset of INPI financial ratios (Licence Ouverte 2.0), not the authenticated INPI API.

        Responses are cached at the edge for 24 hours. A cached response does not count against the rate limit.'
      parameters:
      - name: siren
        in: path
        required: true
        description: The nine-digit identifier of a French legal entity. Spaces, dots and dashes are accepted and ignored.
        schema:
          type: string
          pattern: ^[0-9 .-]{9,13}$
        examples:
          doctolib:
            value: '794598813'
            summary: Doctolib
          edf:
            value: '552081317'
            summary: EDF
      - name: If-None-Match
        in: header
        required: false
        description: Send the previous `ETag` to get a 304 when nothing has changed.
        schema:
          type: string
      responses:
        '200':
          description: The filed accounts, fiscal year by fiscal year.
          headers:
            ETag:
              description: Weak validator of this representation.
              schema:
                type: string
            Cache-Control:
              description: Shared caches may keep this for 24 hours.
              schema:
                type: string
            Link:
              description: 'RFC 8631 discovery links: `service-desc` points at this document, `service-doc` at the human documentation, `license` at the data licence.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Financials'
        '304':
          description: Your `If-None-Match` matched. No body.
        '400':
          description: The SIREN is not nine digits.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#invalid-siren
                title: Invalid SIREN
                status: 400
                detail: A SIREN is the nine-digit identifier the French business register assigns to a legal entity.
        '404':
          description: The company has no published accounts on record.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#no-financial-statements
                title: No financial statements
                status: 404
                detail: No published annual accounts are on record for SIREN 123456789 in the INPI ratios dataset. The company may exist and never have filed, have filed under confidentiality, or have filed accounts the INPI has not processed yet.
        '405':
          description: This endpoint is read-only.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#method-not-allowed
                title: Method not allowed
                status: 405
                detail: This endpoint is read-only. POST is not supported; use GET.
        '429':
          description: Rate limit exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#rate-limit-exceeded
                title: Too many requests
                status: 429
                detail: This API allows 30 reads per minute per IP address.
          headers:
            Retry-After:
              description: Seconds to wait.
              schema:
                type: integer
            RateLimit-Limit:
              schema:
                type: integer
            RateLimit-Remaining:
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '503':
          description: The upstream source did not answer. This says nothing about whether the company exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#upstream-unavailable
                title: Upstream register unavailable
                status: 503
                detail: The upstream register did not answer in time.
components:
  schemas:
    Financials:
      type: object
      required:
      - siren
      - statements
      - coverage
      - attribution
      - served_by
      - terms
      - documentation
      - notice
      properties:
        siren:
          type: string
          examples:
          - '794598813'
        statements:
          type: array
          description: 'Most recent first, both perimeters mixed: `perimeter` tells them apart on every entry.'
          items:
            $ref: '#/components/schemas/FinancialStatement'
        coverage:
          type: object
          required:
          - statements
          - perimeters
          - confidential_filings_excluded
          properties:
            statements:
              type: integer
              description: How many entries are served, all perimeters together.
            perimeters:
              type: array
              items:
                type: string
                enum:
                - legal_entity
                - group
              description: Which perimeters the company has filed under.
            confidential_filings_excluded:
              type: boolean
              description: 'Always true: a confidential filing is absent, never served as zeros.'
        attribution:
          $ref: '#/components/schemas/Attribution'
        served_by:
          $ref: '#/components/schemas/ServedBy'
        terms:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        notice:
          type: string
          description: What the data does and does not say.
    Problem:
      type: object
      description: Error format, following RFC 9457 (Problem Details for HTTP APIs).
      required:
      - type
      - title
      - status
      - detail
      properties:
        type:
          type: string
          format: uri
          description: Stable URI identifying the problem kind.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          description: The path that was requested.
    Attribution:
      type: array
      description: Source and retrieval date. Reusing this data requires citing both; they travel in the payload so that they reach consumers who never see the website.
      items:
        type: object
        required:
        - name
        - url
        - licence
        - retrieved
        properties:
          name:
            type: string
          url:
            type: string
            format: uri
          licence:
            type: string
          retrieved:
            type: string
            format: date-time
    Timeline:
      type: object
      required:
      - siren
      - legal_name
      - timeline
      - proceedings
      - insolvency
      - coverage
      - attribution
      - served_by
      - terms
      - documentation
      - notice
      properties:
        siren:
          type: string
          examples:
          - '794598813'
        legal_name:
          type:
          - string
          - 'null'
          description: The name as the gazette last published it. Null when no announcement names the company.
        timeline:
          type: array
          description: One entry per field that has changed at least once.
          items:
            type: object
            required:
            - field
            - label
            - changes
            - first_known
            - current
            - history
            properties:
              field:
                type: string
                enum:
                - share_capital
                - legal_name
                - legal_form
                - registered_office
                - stated_activity
              label:
                type: string
                description: Human-readable field name, in English.
              changes:
                type: integer
                description: 'How many times the value changed. `history` holds one more entry than this: the first is a starting point, not a change.'
              first_known:
                $ref: '#/components/schemas/Step'
              current:
                $ref: '#/components/schemas/Step'
              history:
                type: array
                items:
                  $ref: '#/components/schemas/Step'
        proceedings:
          type: array
          description: 'Insolvency judgments, most recent first. Separate from `timeline` on purpose: a timeline entry follows the value of a field, a judgment is a dated event. Empty for a company that has never been through one.'
          items:
            $ref: '#/components/schemas/Proceeding'
        insolvency:
          description: 'Where the company stands under insolvency law, or null when no judgment installed a status. Do not recompute this from `proceedings`: a closure cancels a liquidation, a set-aside cancels the judgment it sets aside, and two judgments can share a date.'
          oneOf:
          - $ref: '#/components/schemas/Insolvency'
          - type: 'null'
        coverage:
          type: object
          required:
          - announcements_read
          - complete
          - earliest_possible_year
          properties:
            announcements_read:
              type: integer
              description: How many announcements actually describe this company.
            complete:
              type: boolean
              description: False when the gazette stopped answering mid-read. The timeline is then a beginning, and the response is not cached.
            earliest_possible_year:
              type: integer
              examples:
              - 2008
        attribution:
          $ref: '#/components/schemas/Attribution'
        served_by:
          $ref: '#/components/schemas/ServedBy'
        terms:
          type: string
          format: uri
          description: The terms of use, absolute, as every answer of the fleet carries them.
        documentation:
          type: string
          format: uri
          description: The human documentation, absolute.
        notice:
          type: string
          description: What the data does and does not say.
    Amount:
      type: object
      description: A monetary amount with its currency beside it, never announced once at the top.
      required:
      - value
      - currency
      properties:
        value:
          type: number
          examples:
          - 311448000
        currency:
          type: string
          enum:
          - EUR
    Insolvency:
      type: object
      required:
      - status
      - since
      properties:
        status:
          type: string
          enum:
          - safeguard
          - receivership
          - recovery_plan
          - liquidation
          - closed_for_insufficient_assets
          - closed_debts_paid
          - judgment_set_aside
        since:
          type: string
          format: date
          description: The date of the judgment that installed it.
        source:
          type: string
          format: uri
    Step:
      type: object
      required:
      - date
      - value
      properties:
        date:
          type: string
          format: date
          description: Publication date of the announcement that carried this value.
          examples:
          - '2020-02-11'
        value:
          type: string
          description: 'The value exactly as the register published it, in French. Names and addresses are not translated: translating them would invent a fact nobody recorded.'
          examples:
          - 157 630,69 EUR
        amount:
          type: object
          description: The same value as a number, present only on monetary fields. Provided so that consumers never have to parse the French formatting of `value`.
          required:
          - value
          - currency
          properties:
            value:
              type: number
              examples:
              - 157630.69
            currency:
              type: string
              description: ISO 4217 code.
              examples:
              - EUR
        source:
          type: string
          format: uri
          description: The gazette announcement that published this value. Every step is verifiable.
          examples:
          - https://www.bodacc.fr/annonce/detail-annonce/A/20200028/1234
    ServedBy:
      type: object
      description: Which service produced this response. `attribution` says where the data comes from; this says who served it. A record copied into another database can then be traced back, if only to know where to report a wrong line.
      required:
      - name
      - url
      properties:
        name:
          type: string
          examples:
          - Auregistre
        url:
          type: string
          format: uri
          examples:
          - https://auregistre.fr/api
    FinancialStatement:
      type: object
      required:
      - fiscal_year_end
      - fiscal_year
      - perimeter
      - revenue
      - revenue_change_percent
      - gross_margin
      - ebitda
      - ebit
      - net_income
      - ratios
      properties:
        fiscal_year_end:
          type: string
          format: date
          examples:
          - '2024-12-31'
        fiscal_year:
          type: string
          examples:
          - '2024'
        perimeter:
          type: string
          enum:
          - legal_entity
          - group
          description: '`legal_entity`: the accounts of the one company registered under this SIREN. `group`: the consolidated accounts of its group. The two never add up, and a holding can carry a revenue of zero beside a group revenue in the billions.'
        revenue:
          description: 'Null when not published, or when the dataset carries a zero beside a non-zero net income: an empty field, not a measurement.'
          oneOf:
          - $ref: '#/components/schemas/Amount'
          - type: 'null'
        revenue_change_percent:
          type:
          - number
          - 'null'
          description: Against the previous fiscal year OF THE SAME PERIMETER, to one decimal. Null without such a year. The only computed figure in this response.
        gross_margin:
          description: Gross margin, as filed.
          oneOf:
          - $ref: '#/components/schemas/Amount'
          - type: 'null'
        ebitda:
          description: Excedent brut d'exploitation, as filed.
          oneOf:
          - $ref: '#/components/schemas/Amount'
          - type: 'null'
        ebit:
          description: Resultat d'exploitation, as filed.
          oneOf:
          - $ref: '#/components/schemas/Amount'
          - type: 'null'
        net_income:
          description: Null when not published, or when the dataset carries a zero beside a non-zero revenue.
          oneOf:
          - $ref: '#/components/schemas/Amount'
          - type: 'null'
        ratios:
          type: object
          description: The thirteen ratios the INPI computes. The unit is in the field name; null means the INPI did not compute it.
          properties:
            ebitda_margin_percent:
              type:
              - number
              - 'null'
              description: EBITDA over revenue, in percent.
            financial_autonomy_percent:
              type:
              - number
              - 'null'
              description: Equity over total balance sheet, in percent.
            debt_ratio_percent:
              type:
              - number
              - 'null'
              description: Financial debt over equity, in percent.
            current_ratio:
              type:
              - number
              - 'null'
              description: Current assets over current liabilities.
            cash_flow_to_revenue_percent:
              type:
              - number
              - 'null'
              description: Cash flow from operations over revenue, in percent.
            debt_repayment_capacity_years:
              type:
              - number
              - 'null'
              description: Net financial debt over cash flow, in years.
            interest_coverage:
              type:
              - number
              - 'null'
              description: EBIT over financial charges.
            working_capital_to_revenue_percent:
              type:
              - number
              - 'null'
              description: Operating working capital requirement over revenue, in percent.
            working_capital_days:
              type:
              - number
              - 'null'
              description: The same requirement, in days of revenue.
            inventory_turnover_days:
              type:
              - number
              - 'null'
              description: Inventory over purchases, in days.
            customer_credit_days:
              type:
              - number
              - 'null'
              description: Receivables over revenue, in days.
            supplier_credit_days:
              type:
              - number
              - 'null'
              description: Payables over purchases, in days.
    Proceeding:
      type: object
      required:
      - date
      - title
      properties:
        date:
          type: string
          format: date
          description: The date of the judgment, not of its publication. The two differ by 16 days at the median, and 14 announcements out of 1,000 fall in a different year.
          examples:
          - '2026-07-22'
        published_on:
          type: string
          format: date
          description: The day the gazette printed it, when it differs from `date`. This is the date that starts legal deadlines.
        title:
          type: string
          description: The judgment as the court clerk published it, in French.
          examples:
          - Jugement d'ouverture d'une procédure de redressement judiciaire
        status:
          type: string
          enum:
          - safeguard
          - receivership
          - recovery_plan
          - liquidation
          - closed_for_insufficient_assets
          - closed_debts_paid
          - judgment_set_aside
          description: 'The status this judgment installs. Absent on the 1.4% of judgments whose wording we refuse to classify: a procedure we cannot read must not manufacture a status, in either direction.'
        appointee:
          type: object
          description: 'Who the court appointed, as the announcement names them. Roles stay in French: they are the words the ruling uses.'
          required:
          - role
          - firm
          - person
          - court
          properties:
            role:
              type: string
              examples:
              - Mandataire judiciaire
            firm:
              type: string
            person:
              type:
              - string
              - 'null'
            court:
              type:
              - string
              - 'null'
              examples:
              - Tribunal de Commerce de Grenoble
        claims_deadline:
          type: string
          format: date
          description: The last day to file a claim, on an OPENING judgment only. The only date in this API that is enforceable against someone.
        source:
          type: string
          format: uri
          description: The announcement that published this judgment.
externalDocs:
  description: Human-readable documentation
  url: https://auregistre.fr/api
x-rate-limit:
  requests: 30
  window_seconds: 60
  scope: ip
  note: 'Edge-cached responses are served without reaching the limiter and do not consume quota. RateLimit-* headers travel on the 429 alone: stored on a cached answer they would tell every caller the quota of the first one.'
x-stability: 'No version in the address and none in the body, because nothing will break: fields are added, never removed or renamed under a caller, and addresses do not move. The launch-day /api/v1/ addresses answer 308 to the same paths without the segment.'