SIREN lookup
Purpose of Use This endpoint queries the PPF (Plateforme Publique de Facturation) — France's official public e-invoicing platform — to retrieve basic directory information about a French legal entity using its 9-digit SIREN number from the Annuaire (Directory) system.
SIREN (Système d'Identification du Répertoire des Entreprises) is the unique 9-digit identifier assigned to French companies by INSEE. Through this endpoint, callers can retrieve the company's legal name, entity type (public/private), administrative status, and directory record details in a single request.
Typical use cases:
- Verifying that a SIREN is registered and active in the PPF Annuaire before sending an e-invoice to a French recipient
- Determining whether a company belongs to the public or private sector in order to select the correct e-invoicing channel
- Checking the diffusible (publishable) status of a legal entity during the onboarding flow
- Retrieving the company's PPF instance ID for use in subsequent directory queries
Endpoint Information
| Property | Value |
|---|---|
| URL | /annuaire/FR/siren/{siren} |
| 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/siren/123456789' \
--header 'Accept: application/json' \
--header 'R-Auth: <JWT_TOKEN>'
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| siren | String | Yes | The 9-digit French SIREN number for the target legal entity |
Path Parameter Values
| Field | Rule | Valid Example | Invalid Example |
|---|---|---|---|
| siren | Exactly 9 digits; leading zeros are preserved | 271688503 | 271-685, 27168850, ABCDEFGHI, 2716885030 |
Responses
200 - Successful Response
{
"siren": "271688503",
"raisonSociale": "SIREN_271688503",
"typeEntite": "Privée assujettie",
"etatAdministratif": "A",
"diffusible": "O",
"historisation": {
"idInstance": 1003843,
"dateDebutEffet": null,
"dateDefinition": null,
"creePar": null,
"masque": null
}
}
400 - Bad Request
Returned when the SIREN parameter does not consist of exactly 9 digits.
{
"error": "VALIDATION_ERROR",
"message": "SIREN must be exactly 9 digits for French companies",
"code": "FR_SIREN_INVALID"
}
Description: The client has sent a value with fewer or more than 9 digits, or a non-numeric character. The SIREN format is validated against the regex pattern ^\d{9}$.
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"
}
Description: The token has expired, its signature is invalid, or the header is missing. The system internally attempts to obtain a new token; if that also fails, this error is propagated to the client. Token TTL is 50 minutes.
403 - Forbidden
Returned when the authenticated user does not have access rights to the requested SIREN record.
{
"error": "FORBIDDEN",
"message": "Access denied to this resource",
"code": "ACCESS_DENIED"
}
Description: Authentication succeeds, but the authorization layer rejects the request. This may result from PPF Annuaire access policies or user role restrictions.
404 - Not Found
Returned when the provided SIREN number is not registered in the PPF Annuaire.
{
"error": "NOT_FOUND",
"message": "No entity found for SIREN: 271688503",
"code": "COMPANY_NOT_FOUND"
}
Description: Even though the SIREN format is valid, no matching record exists in France's official directory. The company may not yet have registered with PPF, or the record may have been removed.
422 - Unprocessable Entity
Returned when the request is technically valid but cannot be processed due to business logic constraints.
{
"error": "UNPROCESSABLE_ENTITY",
"message": "PPF Annuaire registration failed. Please verify your company information and try again.",
"code": "FR_PPF_ONBOARD_FAILED"
}
Description: Typically triggered by data inconsistencies in the PPF system for the queried SIREN, or when the company is not marked as publishable (diffusible).
500 - Internal Server Error
Returned when an unexpected error occurs while communicating with the upstream PPF Annuaire service.
{
"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 from the PPF Annuaire service.