Get Annuaire Info

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.