Auregistre Insolvency API

openapi: 3.2.0
info:
  title: Auregistre Insolvency 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: insolvency
  description: Aggregate counts of insolvency openings, over the scopes the website already publishes as pages.
paths:
  /insolvencies:
    get:
      tags:
      - insolvency
      operationId: getInsolvencies
      summary: Insolvency openings in France, twelve months against the twelve before
      description: 'Judgments OPENING an insolvency procedure, counted over a rolling twelve months and against the twelve before,

        month by month, by nature, and ranked by department.


        Closures are excluded: they are the opposite of a new failure. The current month is excluded too, because a month

        still running reads as a collapse. The same figures are on the `/defaillances` page, and its monthly series has been

        downloadable as CSV for months: this address adds no new data, it hands a machine what a reader could already copy.


        Responses are cached at the edge for 24 hours.'
      parameters:
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The national barometer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insolvencies'
        '304':
          description: Your `If-None-Match` matched. No body.
        '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.
        '503':
          description: The gazette did not answer. No count is served rather than a zero.
          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 French official gazette did not answer in time.
  /insolvencies/department/{code}:
    get:
      tags:
      - insolvency
      operationId: getInsolvenciesByDepartment
      summary: The same barometer, for one department
      description: The code is checked against the closed list the website publishes as pages. An unknown code is a 404, never a composed query.
      parameters:
      - name: code
        in: path
        required: true
        description: Two-digit department code, 2A or 2B for Corsica, three digits overseas.
        schema:
          type: string
        examples:
          isere:
            value: '38'
            summary: Isère
      responses:
        '200':
          description: The barometer for that department.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insolvencies'
        '404':
          description: No such department.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#no-such-endpoint
                title: No such department
                status: 404
                detail: 99 is not a French department code.
  /insolvencies/trade/{slug}:
    get:
      tags:
      - insolvency
      operationId: getInsolvenciesByTrade
      summary: The same barometer, for one trade
      description: 'The slug is checked against a closed table, and a refusal lists the trades that exist.


        A trade is read from the WORDS of the activity the gazette prints, not from an activity code: the gazette publishes a

        sentence, not a code. Two trades can therefore overlap on one announcement.'
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          enum:
          - restauration
          - batiment
          - renovation
          - commerce-de-detail
          - bar
          - habillement
          - plomberie
          - nettoyage
          - alimentation
          - boulangerie
          - traiteur
          - transport
          - informatique
          - conseil
          - coiffure
          - taxi
          - evenementiel
          - electricite
          - esthetique
          - garage
          - jardinage
          - immobilier
          - securite
          - boucherie
          - hebergement
        examples:
          restauration:
            value: restauration
            summary: Restauration
      responses:
        '200':
          description: The barometer for that trade.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Insolvencies'
        '404':
          description: No such trade.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#no-such-endpoint
                title: No such trade
                status: 404
                detail: boulangerie-artisanale is not one of the trades this API covers.
components:
  schemas:
    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
    Insolvencies:
      type: object
      required:
      - scope
      - window
      - reference
      - change_percent
      - monthly
      - by_nature
      - attribution
      - served_by
      - terms
      - documentation
      - notice
      properties:
        scope:
          type: object
          required:
          - kind
          - code
          - name
          - page_url
          properties:
            kind:
              type: string
              enum:
              - country
              - department
              - trade
            code:
              type:
              - string
              - 'null'
            name:
              type: string
              description: 'In French: it is a published value, not a UI label.'
            page_url:
              type: string
              format: uri
              description: The page that shows the same thing to a human.
        window:
          $ref: '#/components/schemas/InsolvencyWindow'
        reference:
          allOf:
          - $ref: '#/components/schemas/InsolvencyWindow'
          description: The twelve months before the window, to compare against.
        change_percent:
          type:
          - number
          - 'null'
          description: 'Null when the reference is zero: "+100%" from nothing means nothing, and a place with no failure last year did not explode, it started.'
        monthly:
          type: array
          description: Both windows, month by month, oldest first.
          items:
            type: object
            required:
            - month
            - openings
            properties:
              month:
                type: string
                examples:
                - 2026-07
              openings:
                type: integer
        by_nature:
          type: array
          description: 'Three separate counts over the window. They do NOT add up to its total: a judgment naming two procedures answers two filters, which overshoots the total by well under one percent.'
          items:
            type: object
            required:
            - nature
            - openings
            properties:
              nature:
                type: string
                enum:
                - liquidation
                - receivership
                - safeguard
              openings:
                type:
                - integer
                - 'null'
                description: Null when that one count went unanswered, the rest of the response standing.
        by_department:
          type: array
          description: Ranking over the window, largest first. Present on the country scope only. Codes the site has no page for are left out.
          items:
            type: object
            required:
            - code
            - name
            - openings
            properties:
              code:
                type: string
                examples:
                - '75'
              name:
                type: string
                examples:
                - Paris
              openings:
                type: integer
        attribution:
          $ref: '#/components/schemas/Attribution'
        served_by:
          $ref: '#/components/schemas/ServedBy'
        terms:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        notice:
          type: string
    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
    InsolvencyWindow:
      type: object
      required:
      - from
      - to
      - openings
      properties:
        from:
          type: string
          examples:
          - 2025-08
        to:
          type: string
          description: 'Last month included. The current month is never in it: still running, it would read as a collapse.'
          examples:
          - 2026-07
        openings:
          type: integer
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.'