Auregistre Watch API

openapi: 3.2.0
info:
  title: Auregistre Watch 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: watch
  description: What the gazette published on companies you already track. It takes identifiers, never criteria, so it is not a search either.
paths:
  /changes:
    get:
      tags:
      - watch
      operationId: getChanges
      summary: What the gazette published on companies you track
      description: 'Pass the SIREN you already hold and a date; get back what the gazette printed about each of them since.


        **Entries are filtered on the publication date, not on the date of the act.** The two differ by 16 days at the median,

        so a watch filtered on the act would never see a judgment ruled before its last visit and published after.


        Up to 20 companies per call, and each one spends one unit of the rate limit.

        Values that are not nine digits are ignored rather than refused; a call where none are left is a 400.


        Responses are cached at the edge for one hour. Sort your SIREN or reuse the same order: the cache key is the URL.'
      parameters:
      - name: siren
        in: query
        required: true
        description: Comma-separated nine-digit identifiers, up to 20. Spaces, dots and dashes are ignored.
        schema:
          type: string
        examples:
          deux:
            value: 794598813,552081317
            summary: Doctolib and EDF
      - name: since
        in: query
        required: false
        description: Publication date to look back to, ISO 8601. Defaults to 30 days ago. An unreadable value falls back to the default rather than being refused.
        schema:
          type: string
          format: date
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: One entry per company, whether or not anything moved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Changes'
        '304':
          description: Your `If-None-Match` matched. No body.
        '400':
          description: No readable SIREN was passed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://auregistre.fr/api#invalid-siren
                title: No company requested
                status: 400
                detail: Pass the companies to watch in the siren query parameter, comma-separated.
        '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 company reads per minute per IP address.
        '503':
          description: The gazette did not answer.
          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.
components:
  schemas:
    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
    Changes:
      type: object
      required:
      - since
      - companies
      - attribution
      - served_by
      - terms
      - documentation
      - notice
      properties:
        since:
          type: string
          format: date
          description: The date the window starts, as it was understood. Echoed so that a caller never believes it asked for something else.
        companies:
          type: array
          description: One entry per readable SIREN, in ascending order, whether or not anything moved.
          items:
            type: object
            required:
            - siren
            - legal_name
            - changes
            - complete
            properties:
              siren:
                type: string
              legal_name:
                type:
                - string
                - 'null'
              changes:
                type: array
                description: What the gazette published in the window, most recent first.
                items:
                  type: object
                  required:
                  - date
                  - published_on
                  - title
                  properties:
                    date:
                      type: string
                      format: date
                      description: The date of the act.
                    published_on:
                      type: string
                      format: date
                      description: The day the gazette published it. This is the field the window filters on.
                    title:
                      type: string
                      description: The announcement, in French.
                    source:
                      type: string
                      format: uri
              complete:
                type: boolean
                description: 'False when this entry is a beginning: the gazette fell silent, or the company published more announcements in the window than one page of the gazette holds. An empty list with `complete: true` means nothing happened.'
        attribution:
          $ref: '#/components/schemas/Attribution'
        served_by:
          $ref: '#/components/schemas/ServedBy'
        terms:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        notice:
          type: string
    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
    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.
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.'