SIRET lookup

---

Purpose of Use This endpoint queries the PPF (Plateforme Publique de Facturation) Annuaire to retrieve detailed information about a specific French business establishment using its 14-digit SIRET number.

SIRET (Système d'Identification du Répertoire des Établissements) is a unique 14-digit code that identifies a specific establishment (branch, headquarters, factory, etc.) of a French company. The first 9 digits are the company's SIREN number; the last 5 digits are the NIC (Numéro Interne de Classement) code that distinguishes the specific establishment.

Typical use cases:

• Verifying that a SIRET is registered and active in the PPF Annuaire before sending an e-invoice to a French establishment
• Retrieving the branch address (postal code, city, country) and establishment-level invoicing parameters
• Determining whether the establishment is publishable (diffusible) and its administrative status
• Obtaining the idInstance value to use in onboarding or routing flows

Endpoint Information

Property	Value
URL	/annuaire/FR/siret/{siret}
Method	GET
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-fr-stage.docnova.ai/ Production Environment URLhttps://api-fr.docnova.ai/
Authorization	R-Auth header (JWT token)

Example Request

curl --location 'https://api-fr-stage.docnova.ai/annuaire/FR/siret/27168850399286' \
--header 'Accept: application/json' \
--header 'R-Auth: <JWT_TOKEN>'

Request Parameters

Field	Type	Required	Description
siret	String	Yes	The 14-digit French SIRET number for the target establishment

Path Parameter Values

Field	Rule	Valid Example	Invalid Example
siret	Exactly 14 digits; leading zeros are preserved. The first 9 digits must match the parent company's SIREN.	27168850399286, 00000000000001	2716885039928 (13 digits), 271688503992860 (15 digits), 2716-8850-3992-86, ABCDEFGHIJKLMN

Responses

200 - Successful Response

{
  "siret": "27168850399286",
  "siren": "271688503",
  "denomination": "Valideur 27168850399286",
  "typeEtablissement": "S",
  "diffusible": "O",
  "etatAdministratif": "A",
  "adresse": {
    "ligneAdresse1": "test street",
    "ligneAdresse2": null,
    "ligneAdresse3": null,
    "codePostal": "75001",
    "localite": "test city",
    "codePays": "FR",
    "libellePays": "France (la)",
    "subDivisionPays": null
  },
  "historisation": {
    "idInstance": 1015764,
    "dateDebutEffet": null,
    "dateDefinition": null,
    "creePar": null,
    "masque": null
  }
}

Response Fields

Field	Type	Description
siret	String	The queried 14-digit SIRET number.
siren	String	The parent company's 9-digit SIREN number.
denomination	String	Official establishment name (may differ from parent company name).
typeEtablissement	String	Establishment type (e.g., 'S' = secondary, 'P' = principal).
diffusible	String	Publishability flag: "O" = Yes, "N" = No.
etatAdministratif	String	Administrative status enum (e.g., "A", "F").
adresse	Object	Establishment address details.
historisation	Object	Audit metadata for this PPF directory record. Use historisation.idInstance with the PPF Directory Lookup (./ppf-directory-lookup) endpoint to retrieve the company's platform registration and verify whether they have connected to a PA.

400 - Bad Request

Returned when the SIRET parameter does not consist of exactly 14 digits.

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid SIRET: must be exactly 14 digits",
  "code": "FR_SIRET_INVALID"
}

Description: The client has sent a value with fewer or more than 14 digits, or a non-numeric character. The SIRET format is validated against the regex pattern ^\d{14}$.

401 - Unauthorized

Returned when the JWT token in the R-Auth header cannot be verified.

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired authentication token",
  "code": "AUTH_TOKEN_INVALID"
}

403 - Forbidden

{
  "error": "FORBIDDEN",
  "message": "Access denied to this resource",
  "code": "ACCESS_DENIED"
}

404 - Not Found

{
  "error": "NOT_FOUND",
  "message": "No establishment found for SIRET: 27168850399286",
  "code": "COMPANY_NOT_FOUND"
}

422 - Unprocessable Entity

{
  "error": "UNPROCESSABLE_ENTITY",
  "message": "PPF Annuaire registration failed. Please verify your company information and try again.",
  "code": "FR_PPF_ONBOARD_FAILED"
}

500 - Internal Server Error

{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred while contacting PPF Annuaire",
  "code": "GENERAL_ERROR"
}

Description: May be triggered by the upstream PPF API being unreachable, a timeout (default 15,000 ms), or an unexpected response format returned by the PPF Annuaire service.