> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up directory entries by SIREN

> Returns all entries from the PPF Annuaire that
match the given French SIREN.

Returns the active directory entries from the PPF Annuaire that match the given SIREN. A SIREN may have multiple registered parties (one per SIRET / suffix / routing code), so the response is always a list.

Results are paginated with the `offset` and `limit` query parameters (`limit` defaults to 50, max 200). While more pages remain, the response includes `next_offset`, pass it back as `offset` to fetch the next page.

An empty `results` array means the SIREN is not currently registered in the Annuaire.

Only available to live workspaces — sandbox enrollments receive `403 Forbidden`.


## OpenAPI

````yaml GET /apps/gov-fr/v1/directory/siren/{siren}
openapi: 3.1.0
info:
  contact:
    email: dev@invopop.com
    name: Invopop Developers
  description: >-
    Set of end-points for the France app, including lookups against the PPF
    Annuaire (French e-invoicing directory).
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: France Service API
  version: 0.1.0
servers:
  - description: production
    url: https://api.invopop.com
security:
  - InvopopAuth: []
paths:
  /apps/gov-fr/v1/directory/siren/{siren}:
    get:
      summary: Look up directory entries by SIREN
      description: |-
        Returns all entries from the PPF Annuaire that
        match the given French SIREN.
      operationId: lookupDirectoryBySIREN
      parameters:
        - name: siren
          in: path
          required: true
          description: 9-digit French SIREN identifier of the company to look up.
          schema:
            type: string
            example: '123456789'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: |-
            One page of matching directory entries. `count` may be `0` if the
            SIREN is not present in the directory.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIRENLookupResponse'
              examples:
                found:
                  summary: SIREN present in the directory
                  value:
                    siren: '123456789'
                    count: 1
                    results:
                      - id_instance: '1020993'
                        siren: '123456789'
                        siret: ''
                        routing_code: ROUTE123
                        platform_id: '0431'
                        nature: M
                        identifier: '269909452'
                        suffix: ''
                        start_date: '20251227'
                        end_date: ''
                        effective_end_date: '20280402'
                        created_at: '2026-01-15T10:00:00Z'
                        updated_at: '2026-01-15T10:00:00Z'
                paginated:
                  summary: First page with more results available (`?limit=1`)
                  value:
                    siren: '123456789'
                    count: 1
                    results:
                      - id_instance: '1020993'
                        siren: '123456789'
                        siret: ''
                        routing_code: ROUTE123
                        platform_id: '0431'
                        nature: M
                        identifier: '269909452'
                        suffix: ''
                        start_date: '20251227'
                        end_date: ''
                        effective_end_date: '20280402'
                        created_at: '2026-01-15T10:00:00Z'
                        updated_at: '2026-01-15T10:00:00Z'
                    next_offset: 1
                not_found:
                  summary: SIREN not in the directory
                  value:
                    siren: '999999999'
                    count: 0
                    results: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    Offset:
      name: offset
      in: query
      required: false
      description: Number of results to skip, for pagination. Must be non-negative.
      schema:
        type: integer
        minimum: 0
        default: 0
        example: 0
    Limit:
      name: limit
      in: query
      required: false
      description: |-
        Maximum number of results to return. Values outside the `1`–`200`
        range fall back to the default of `50`.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
        example: 50
  schemas:
    SIRENLookupResponse:
      type: object
      required:
        - siren
        - count
        - results
      properties:
        siren:
          type: string
          description: SIREN that was queried.
          example: '123456789'
        count:
          type: integer
          description: Number of directory entries returned on this page.
          example: 1
        results:
          type: array
          description: >-
            Matching directory entries. Empty when the SIREN is not in the
            Annuaire.
          items:
            $ref: '#/components/schemas/DirectoryEntry'
        next_offset:
          type: integer
          description: |-
            Offset of the next page of results. Omitted on the last page —
            its presence means more entries remain.
          example: 50
    DirectoryEntry:
      type: object
      description: |-
        Single entry in the PPF Annuaire. Each entry
        represents one registered electronic address for a SIREN/SIRET.
      properties:
        id_instance:
          type: string
          description: Unique instance identifier from the PPF export.
          example: '1020993'
        siren:
          type: string
          description: 9-digit French SIREN of the company.
          example: '269909452'
        siret:
          type: string
          description: 14-digit French SIRET of the establishment, when applicable.
          example: ''
        routing_code:
          type: string
          description: Routing code used by the PPF to deliver invoices.
          example: ROUTE123
        platform_id:
          type: string
          description: 4-digit identifier of the PA platform that registered the entry.
          example: '0431'
        nature:
          type: string
          description: >-
            Single-letter code for the nature of the entry as classified by the
            Annuaire.
          example: M
        identifier:
          type: string
          description: |-
            Electronic address identifier used for routing. Typically the SIREN,
            optionally with a `_suffix` qualifier when multiple addresses exist
            for the same company.
          example: '269909452'
        suffix:
          type: string
          description: Optional suffix qualifying the identifier.
          example: suffixe1
        start_date:
          type: string
          description: Date from which this entry is active in the Annuaire, as `YYYYMMDD`.
          example: '20251227'
        end_date:
          type: string
          description: Scheduled end date of the entry as `YYYYMMDD`, when set.
          example: ''
        effective_end_date:
          type: string
          description: >-
            Effective end date as `YYYYMMDD`, once the entry has been
            deactivated.
          example: '20280402'
        created_at:
          type: string
          format: date-time
          description: When this entry was first stored in the local mirror.
          example: '2026-01-15T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: When this entry was last refreshed from a PPF export.
          example: '2026-01-15T10:00:00Z'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable description of the error.
          example: missing siren parameter
  responses:
    BadRequest:
      description: The request is malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: missing siren parameter
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: missing enrollment
    Forbidden:
      description: |-
        The directory API is only available to live workspaces. Calls made
        with a sandbox enrollment are rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: directory API is only available for live workspaces
    InternalServerError:
      description: An unexpected server-side error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal server error
  securitySchemes:
    InvopopAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        Authenticate using a valid Invopop enrollment token in the `Bearer`
        scheme.

        Example: `Authorization: Bearer <token>`

````