Get Annuaire Info
Get Information of the Customer in the Annuaire.
Status at Billit : coming soon. First use is for France.
E-invoicing address lookup
Command:
POST /v1/identifiers/lookup
What it does
- A company can have several e-invoicing addresses, and only one can be used per invoice. In France, one SIREN can have many active routing addresses (CTCs) on l'Annuaire de la facturation électronique.
- This endpoint returns all active e-invoicing addresses of a company, so your senders can pick the right one. Each returned address can be used as-is as a customer identifier when you create an invoice.
Supported lookups
| CountryCode | IdentifierType | Returns |
|---|---|---|
| FR | SIREN | All active CTCs of the company based on the Siren number |
| FR | SIRET | The active CTCs of that establishment (Siret), plus the company-level CTCs (Siren) |
API-Request
Example of the Request body :
| Field | Required | Info |
|---|---|---|
| CountryCode | Yes | ISO 3166 alpha-2 country code. Case does not matter. |
| IdentifierType | Yes | SIREN or SIRET for France. Case does not matter. |
| Identifier | Yes | Spaces are allowed, e.g. 123 456 782. Other separators such as dots or dashes are not, so send digits only. |
Example of body:
{
"CountryCode": "FR",
"IdentifierType": "SIREN",
"Identifier": "123456782"
}
Graphical View in Postman: (production environment)
API-Response Example
Example of a Response:
{
"CountryCode": "FR",
"IdentifierType": "SIREN",
"Identifier": "123456782",
"Completeness": "Complete",
"Addresses": [
{
"IdentifierType": "CTC",
"Identifier": "123456782",
"SchemeId": "0225",
"Label": null,
"DiscoveryMethod": "NationalDirectory",
"Details": { "AddressLevel": "SIREN", "Siren": "123456782" }
},
{
"IdentifierType": "CTC",
"Identifier": "123456782_12345678200013_ACHATS",
"SchemeId": "0225",
"Label": null,
"DiscoveryMethod": "NationalDirectory",
"Details": { "AddressLevel": "SIRET_ROUTINGCODE", "Siren": "123456782", "Siret": "12345678200013" }
}
]
}Information about the content on header level (excluding adresses) :
| Field | Info |
|---|---|
| CountryCode, IdentifierType, Identifier | Your input, cleaned up: country code in upper case, identifier type in its standard spelling (e.g. siren becomes SIREN), spaces removed from the identifier. |
| Completeness | Complete: the source is an official register, so these are all active addresses. Partial: the source is best effort and addresses may be missing. France is always Complete. |
| Addresses | Always a list, also with one result. An empty list means no active address is registered. |
Information about the Addresses:
| IdentifierType | Identifier type to use on the customer. France: CTC. |
| Identifier | The address itself. France: the CTC. |
| SchemeId | Peppol EAS code. France: 0225. |
| Label | Name of the address (routing code). Always present, currently always null (will be updated) |
| DiscoveryMethod | How the address was found. France: NationalDirectory. |
| Details | Optional, country specific information. May be missing for other countries. |
Extra Information for Country France:
| AddressLevel | SIREN, SIRET, SIRET_ROUTINGCODE or SIREN_SUFFIX |
| Siren | Always filled |
| Siret | Only for SIRET and SIRET_ROUTINGCODE |
Content examples for the identifier for France:
| CTC format | Identifer Result Example | |
|---|---|---|
| SIREN | SIREN | 123456782 |
| SIRET | SIREN_SIRET | 123456782_12345678200013 |
| SIRET_ROUTINGCODE | SIREN_SIRET_ROUTINGCODE | 123456782_12345678200013_ACHATS |
| SIREN_SUFFIX | SIREN_SUFFIX | 123456782_FACTURES |
Errors
| 400 | Invalid request body | No or unreadable JSON body |
| 400 | _0_IsRequired | CountryCode is missing, or for a supported country IdentifierType or Identifier is missing (one error per field) |
| 400 | IdentifierLookupForCountry_0_IsNotSupported | The country is not supported (checked before the other fields) |
| 400 | IdentifierLookupFor_0_And_1_IsNotSupported | The country is supported, but not this identifier type |
| 400 | _0_IsNoValidSirenOrSiret | France: not a valid SIREN (9 digits) or SIRET (14 digits), or the value does not match the identifier type (e.g. a SIRET sent as SIREN) |
| 401 | ApiKeyNotValid | Missing or invalid API key |
| 502 | TheIdentifierLookupIsUnavailable | The identifier lookup is temporarily unavailable. Please retry later. |
When nothing is found in Annuaire
A company without active addresses is not an error: you get HTTP 200 with "Addresses": [].
You will not be able to send in invoice. Check with your customer on the progress.
Good to know
- Caching: lookup results are cached for 1 hour per company (SIREN). A SIREN and a SIRET of the same company share the cached result. Calling again within that hour returns the same addresses, so there is no need to call the lookup more often.
- Coming soon: labels. Label will be filled with the name of the routing code (e.g. "Achats Lyon") for SIRET_ROUTINGCODE addresses. For the other levels it stays null, which means the address has no label. No change is needed on your side.
Updated about 1 month ago
Did this page help you?