Sovos.com Contact Support

e-invoicing

Compliance Network Implementation Guide

Find an e-invoicing address

Look up directory entries in the Portal Public de Facturation (PPF) and retrieve the electronic addressing information you need to route an invoice correctly.

Consultations API is a shared endpoint across the Sovos Indirect Tax API that uses REST principles over HTTPS and responses in JSON format. Sovos uses the countryCode path parameter to know which directory plugin to use. That means the available filters, metadata fields, and response structure all depend on which directory you're querying.

This guide covers what you get when you query the Annuaire, where countryCode equals FR and directoryType equals Jurisdiction-FR.

How Consultations API works for France

For France, Consultations lets you check whether a trading partner exists in the Annuaire. Consultations dispatches your call to the French jurisdiction plugin, which queries the PPF's Piste API (ligne-annuaire/recherche) on your behalf. Sovos handles authentication to Piste, filter mapping, and pagination, so you interact with one consistent Sovos API contract regardless of what's happening on the side.

CAUTION:

Querying a different country or directory type gives you different filter options and a different response structure.

Authentication

Consultations requires a Bearer token and follows the same authentication process you can find in API authentication.

The token controls which directories and results you can access. Your workspace's Piste credentials determine what it can access, so a request only returns results for the directories your workspace is configured to query. Your API user's role also affects what comes back. An admin role returns full results. A standard role returns partial results.

Prerequisites

Before you can use Consultations for a workspace, Sovos configures the following settings in Compliance Network on your behalf:

Setting Details
Workspace-level Piste credentials (Directory_Config_Jurisdiction_FR)

Sovos provides the following credentials during onboarding:

  • OAuth client ID (client-id)

  • Client secret (client-secret)

  • username

  • User password (userpass)

  • Grant type (grant_type)

  • scope

  • PDP number (pdpnumber)
User role assignment Consultations users need the appropriate role: Admin for full results, or a standard role for partial results.
Environment availability The endpoint is available in both UAT (Mock PPF or Piste test) and Production (live Piste PPF).
Resources

All endpoints use these base URLs:

Environment Server Path prefix
Production https://api.sovos.com /v1/consultations
UAT https://api-test.sovos.com /v1/consultations

Use cases

Sender-side lookup
Before submitting an invoice, verify that the buyer has an active electronic address in the Annuaire.
Receiver-side verification
Confirm your own Annuaire entries are correctly registered.
Master data enrichment
Retrieve Annuaire details (SIREN, SIRET, suffix, electronic addresses) for trading partners to validate Enterprise Resource Planning (ERP) master data.
Troubleshooting routing failures
When an invoice fails to route, query the Annuaire to determine whether the buyer has an active address line.

Get consultation directories by country code

Tip:

Field names are case-insensitive. Sovos uppercases them internally.

Note:

See Resources for the available environments and base URLs and Query parameters for the complete list of parameters.

GET /v1/consultations/{countryCode}/directories

Use this endpoint to get directory records for France, filtered by the query parameters you supply.

Request sample
CODE 
curl --request GET \
  --url 'https://api-test.sovos.com/v1/consultations/FR/directories?endpointCode=369217951&directoryType=Jurisdiction-FR' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Note:

x-correlationId is a unique value you add per request, used for request tracing.

Response sample: 200 OK
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488261097,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 10,
      "totalPages": 1,
      "totalEntries": 5
    },
    "items": [
      {
        "entityName": "",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1048874,
              "DateDebutEffet": "2026-03-22",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Sovos returns the directoryResponse field as a JSON-encoded string in the raw payload, not as a nested object. The sample above shows it already parsed, for readability.

Request samples

Choose among multiple addresses

A single SIREN can have multiple electronic addresses registered in the Annuaire, at the SIRET level, with different suffixes, or for different organizational units. Querying by SIREN alone, as in the first example below, can return several address lines. Consultations result doesn't indicate which address is the correct one for a given invoice.

It's your responsibility to determine the appropriate electronic address based on the buyer's instructions, contractual agreements, or earlier coordination. Don't assume the first result returned is the correct routing target.

Tip:

See Query parameters for the full list of supported query parameters and how each one behaves, including endpointCode, entityName, and the metadata array.

Consultation by SIREN

Looks up every directory record for a single SIREN (French business identification number). Returns every addressing variant registered under that legal entity: the base entity, any SIRET-level establishments, and any addressing suffixes.

Request sample
BASH 
curl --request GET \
  --url 'https://api-qa.sovos.com/v1/consultations/FR/directories?directoryType=Jurisdiction-FR&metadata[0].field=SIREN&metadata[0].value=369217951&page=1&perPage=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Note:

x-correlationId is a unique value you add per request, used for request tracing.

Response sample: 200 OK, five entries returned
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488261097,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 10,
      "totalPages": 1,
      "totalEntries": 5
    },
    "items": [
      {
        "entityName": "",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1048874,
              "DateDebutEffet": "2026-03-22",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": "36921795186949",
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951_36921795186949",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-29",
            "DateFinEffective": "2027-05-29",
            "Historisation": {
              "IdInstance": 1064867,
              "DateDebutEffet": "2026-05-30",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF1",
            "IdentifiantAdressage": "369217951_SUF1",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049108,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF2",
            "IdentifiantAdressage": "369217951_SUF2",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049109,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF7",
            "IdentifiantAdressage": "369217951_SUF7",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-27",
            "DateFinEffective": "2027-05-27",
            "Historisation": {
              "IdInstance": 1062870,
              "DateDebutEffet": "2026-05-28",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Returns five records: the base entity, one SIRET-level establishment, and three addressing suffixes (SUF1, SUF2, and SUF7).

Note:

See Response field reference for a complete list of field descriptions.

Consultation by SIRET

Narrows the search to one establishment by combining a SIREN with a SIRET (the 14-digit establishment identifier). Returns the single matching SIRET-level record.

Request sample
CODE 
curl --request GET \
  --url 'https://api-qa.sovos.com/v1/consultations/FR/directories?directoryType=Jurisdiction-FR&metadata[0].field=SIREN&metadata[0].value=369217951&metadata[1].field=SIRET&metadata[1].value=36921795186949&page=1&perPage=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Tip:

x-correlationId is a unique value you add per request, used for request tracing.

Response sample: 200 OK, one entry returned
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488265172,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 10,
      "totalPages": 1,
      "totalEntries": 1
    },
    "items": [
      {
        "entityName": "",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": "36921795186949",
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951_36921795186949",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-29",
            "DateFinEffective": "2027-05-29",
            "Historisation": {
              "IdInstance": 1064867,
              "DateDebutEffet": "2026-05-30",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Consultation by SIREN with a date window

Searches a SIREN within an effective-date range. Records whose effective period falls in the window come back, including ones that have since ended, which is useful for point-in-time or historical lookups. Omitting perPage on this type of search defaults the page size to 50.

Request sample
BASH 
curl --request GET \
  --url 'https://api-qa.sovos.com/v1/consultations/FR/directories?directoryType=Jurisdiction-FR&metadata[0].field=SIREN&metadata[0].value=369217951&searchStartDate=2026-01-01&searchEndDate=2026-12-31' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Note:

x-correlationId is a unique value you add per request, used for request tracing.

Response sample: 200 OK, 6 entries returned
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488268123,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 50,
      "totalPages": 1,
      "totalEntries": 6
    },
    "items": [
      {
        "entityName": "",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "",
            "IdentifiantAdressage": "369217951",
            "IdentifiantRoutage": "",
            "DateFinEffet": "2026-03-22",
            "DateFinEffective": "2026-03-22",
            "Historisation": {
              "IdInstance": 1048873,
              "DateDebutEffet": "2026-01-22",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF1",
            "IdentifiantAdressage": "369217951_SUF1",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049108,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF2",
            "IdentifiantAdressage": "369217951_SUF2",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049109,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF7",
            "IdentifiantAdressage": "369217951_SUF7",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-27",
            "DateFinEffective": "2027-05-27",
            "Historisation": {
              "IdInstance": 1062870,
              "DateDebutEffet": "2026-05-28",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": "36921795186949",
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951_36921795186949",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-29",
            "DateFinEffective": "2027-05-29",
            "Historisation": {
              "IdInstance": 1064867,
              "DateDebutEffet": "2026-05-30",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1048874,
              "DateDebutEffet": "2026-03-22",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Consultation by SIREN and addressing suffix

Combines a SIREN with a SUFFIXE_ADRESSAGE value to resolve one specific addressing point. Returns the single record matching that suffix.

Request sample
BASH 
curl --request GET \
  --url 'https://api-qa.sovos.com/v1/consultations/FR/directories?directoryType=Jurisdiction-FR&metadata[0].field=SIREN&metadata[0].value=369217951&metadata[1].field=SUFFIXE_ADRESSAGE&metadata[1].value=SUF1&page=1&perPage=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Note:

x-correlationId is a unique value you add per request, used for request tracing

Response sample: 200 OK, one entry returned
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488271110,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 10,
      "totalPages": 1,
      "totalEntries": 1
    },
    "items": [
      {
        "entityName": "",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF1",
            "IdentifiantAdressage": "369217951_SUF1",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049108,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Consultation by endpoint code

Resolves directory records directly from a routing endpoint code, instead of a metadata search. The response echoes the endpointCode on each item and returns every directory record reachable through that endpoint.

endpointCode matches using contains logic against identifiantAdressage, not an exact match. That's why endpointCode=369217951 in the example below returns five records: it matches the base identifier 369217951 itself, plus every composite identifier that contains it as a substring (the SIRET-level and suffix-level addresses).

Request sample
BASH 
curl --request GET \
  --url 'https://api-qa.sovos.com/v1/consultations/FR/directories?endpointCode=369217951&directoryType=Jurisdiction-FR' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-correlationId: <unique-id>'
Note:

x-correlationId is a unique value you add per request, used for request tracing

Response sample: 200 OK, five entries returned
JSON 
{
  "status": 200,
  "message": "OK",
  "success": true,
  "timestamp": 1780488274181,
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 50,
      "totalPages": 1,
      "totalEntries": 5
    },
    "items": [
      {
        "entityName": "",
        "endpointCode": "369217951",
        "directoryResponse": [
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1048874,
              "DateDebutEffet": "2026-03-22",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": "36921795186949",
            "SuffixeAdressage": null,
            "IdentifiantAdressage": "369217951_36921795186949",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-29",
            "DateFinEffective": "2027-05-29",
            "Historisation": {
              "IdInstance": 1064867,
              "DateDebutEffet": "2026-05-30",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF1",
            "IdentifiantAdressage": "369217951_SUF1",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049108,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF2",
            "IdentifiantAdressage": "369217951_SUF2",
            "IdentifiantRoutage": null,
            "DateFinEffet": null,
            "DateFinEffective": "2029-03-19",
            "Historisation": {
              "IdInstance": 1049109,
              "DateDebutEffet": "2026-03-24",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          },
          {
            "Siren": "369217951",
            "Siret": null,
            "SuffixeAdressage": "SUF7",
            "IdentifiantAdressage": "369217951_SUF7",
            "IdentifiantRoutage": null,
            "DateFinEffet": "2027-05-27",
            "DateFinEffective": "2027-05-27",
            "Historisation": {
              "IdInstance": 1062870,
              "DateDebutEffet": "2026-05-28",
              "DateDefinition": null,
              "Masque": null,
              "CreePar": null
            },
            "CodeRoutage": null,
            "Plateforme": null,
            "UniteLegale": null,
            "Etablissement": null
          }
        ]
      }
    ]
  }
}

Query parameters

Consultations has three query parameters. Knowing how these parameters behave helps you build the right query on the first try.

Parameter Type Description Example
endpointCode String Electronic addressing identifier. Sovos internally maps to the IDENTIFIANT_ADRESSAGE metadata key and matched using a contains (partial) match against identifiantAdressage. If you also pass IDENTIFIANT_ADRESSAGE explicitly in the metadata array, that value is silently ignored. endpointCode takes precedence. 369217951
endpointScheme String Scheme qualifier for endpointCode. Accepted and echoed back in the response, but not used as a filter in the French plugin. urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088
entityName String Accepted by the API, but not used in the French plugin. Has no effect on the results returned. ACME SAS
Parameter-specific behavior

entityName and endpointScheme accept a string value, but neither one narrows your results in the French plugin. If you rely on them to filter, you get back everything that matches your other filters, not a narrower set.

endpointCode works differently. It does filter, but it overrides any IDENTIFIANT_ADRESSAGE value you also pass in metadata, so combining the two doesn't apply both filters.

Formatting the metadata parameter
The Response field reference page describes metadata as an array of objects, each with a field and a value. In an actual request, send this as indexed query parameters, not as a single JSON value:
CODE 
?metadata[0].field=SIREN&metadata[0].value=369217951
To combine filters, add another indexed entry:
CODE 
?metadata[0].field=SIREN&metadata[0].value=369217951&metadata[1].field=SUFFIXE_ADRESSAGE&metadata[1].value=SUF1

SIRET and SIREN as query parameters

Using SIRET and SIREN numbers as parameters in your query returns different results. Searching by SIREN alone can return multiple address lines for the same legal entity: the base entity record, any SIRET-level establishment records, and any addressing-suffix records. Searching by SIREN combined with SIRET narrows the result to the single record for that specific establishment.

Parameter combination What it returns When to use
SIREN only Returns every address line registered under the legal entity. Use this when you want the full picture of an entity's Annuaire presence, or when you don't yet know which specific establishment or suffix you need.
SIREN and SIRET Returns the one address line for that specific establishment. Use this when you already know the establishment you need to route to, for example from the buyer's invoicing instructions.

Supported metadata[n].field values and matching rules

Metadata field Piste filter Match type Description
SIREN filtres.siren Exact 9-digit SIREN of the legal entity
SIRET filtres.siret Exact 14-digit SIRET of a specific establishment
SUFFIXE_ADRESSAGE filtres.suffixeAdressage Exact Addressing suffix for sub-addresses
CODE_ROUTAGE filtres.identifiantRoutage Contains (partial) Routing identifier.

IDENTIFIANT_ADRESSAGE (populated automatically from endpointCode, see above) also uses a contains match. All other filters use exact matching. For example, searching endpointCode=10000000 matches entries like 100000009 or 100000009_00001.

Time-period and null filters

Time-period filter
SovosSovos applies the historisation (time-period) filter only when you supply both searchStartDate and searchEndDate. If you provide only one, Sovos silently ignores the date filter and returns results without time-period scoping.
Null filters
Sovos omits null filters. It sends only filters with non-null values to Piste. You don't need to explicitly pass empty or null values for filters you aren't using.

Error handling

Error responses

Every error response shares one envelope, with the error detail nested under errors:

JSON 
{
  "timestamp": 1571936582195,
  "status": "<status code>",
  "success": false,
  "message": "<summary message>",
  "errors": [
    { "subCode": "<code>", "message": "<detail>" }
  ]
}
Status Message Example subCode Example errors[].message
400 Invalid Request TRA-00 The required field XXXXX was not specified.
401 Invalid Credentials authorization.invalidCredentials Invalid Credentials
403 Forbidden config.{errorMessage} User does not have the required permission
404 NotFound config.{errorMessage} The {requested-resource} was not found
500 Internal Server Error system.error The required field XXXXX was not specified.

Error handling and resilience

Sovos applies the following resilience policies when calling Piste on your behalf:

Transient error retry
Three retries, with exponential backoff (two seconds, four seconds, eight seconds).
Circuit breaker
Opens after five consecutive failures and stays open for two seconds.
OAuth token refresh
If Piste returns HTTP 401, Sovos automatically refreshes the OAuth token and retries the request once.

From your side, these retries are transparent: the API either returns results, or an error response after retries are exhausted.

Response field reference

Envelope

Envelope field Description Example
status or message HTTP status and text. 200 or OK
success Boolean call-success flag. true
timestamp Epoch milliseconds of the response. 1780488261097
data.pageState Pagination metadata for the result set. { page, perPage, totalPages, totalEntries }
data.items[] Result wrapper. directoryResponse is a JSON-encoded array of records. [ { entityName, directoryResponse } ]

Directory record

Record field Description Example
Siren Nine-digit French legal-entity identifier. 369217951
Siret 14-digit establishment identifier. Null at the entity level. 36921795186949
SuffixeAdressage Addressing suffix, when the record is a suffix-level address. SUF1
IdentifiantAdressage Composite addressing identifier used for routing. 369217951_SUF1
IdentifiantRoutage Routing identifier, when assigned. null
DateFinEffet Effective end date of the record. Null means open-ended. 2027-05-29
DateFinEffective Effective end date actually applied. 2029-03-19
Historisation Versioning block: instance ID and effective-start date. { IdInstance, DateDebutEffet, DateDefinition, Masque, CreePar }
CodeRoutage Routing code details, including address and routing identifier type, when present. null
Plateforme Routing platform, when present. null
UniteLegale Legal entity details (denomination, legal category), when returned by Piste. null
Etablissement Establishment details, present when the record is SIRET-level. null
Note:

See Choose among multiple addresses for more details about the correct address for a given invoice.

Last updated: September 9, 2026