Sovos.com Contact Support

e-invoicing

Indirect Tax API

Print page

Configuration

Starting with version 2 of the Configurations resource, you can now create the necessary information to start archiving invoices.

Other backend configuration is handled by the Sovos Professional Services team during the implementation phase. If the company already exists and the client is using the Continuous Transaction Controls (CTC) process for a specific country, then a separate configuration for archiving isn't needed.

Prerequisites

These are the configuration prerequisites:

  • An account on developer.sovos.com to use Configurations v2. This also requires customers (for now) to contact the Sovos Professional Services team to obtain special authorization to use it and to obtain their organization ID.

  • A configured company and product.

Note:

Organization IDs differ between Sandbox and Production.

Once customers have access to Configuration v2 and have obtained their organization ID, they can call the dedicated Create a Company endpoint to create a company and assign a product.

Create a company and assign a product

Sandbox
To create a company with a product in the sandbox environment, use /v2/configurations/organizations/YOUR-ORG-ID/companies by configuring the company with the Sovos Professional Services team or choosing self-service as an option.
Production
To create a company with a product in the production environment, use /v2/configurations/organizations/YOUR-ORG-ID/companies and the credentials obtained from developer.sovos.com, along with the appropriate organization ID.
Note:

If the products array is empty, the created Company will acquire all the products assigned to the organization.

Always save the company ID value from the response when creating a company, as it is required for future calls. To find it, look for the YOUR-COMPANYID value in the samples.

Request samples

Here is a request sample for creating a company and assigning a product:

JSON 
curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "taxId": "YOUR-TAXID",
    "legalName": "YOUR-LEGAL-NAME",
    "dba": "YOUR-DOING-BUSINESS-AS-NAME",
    "products": ["pl_Faktura__1.0", "pl_Faktura_Polling_1.0"]
}'

Here is a request sample for creating a company and assigning a product (with an empty products list):

JSON 
curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "taxId": "YOUR-TAXID",
    "legalName": "YOUR-LEGAL-NAME",
    "dba": "YOUR-DOING-BUSINESS-AS-NAME",
    "products": []
}'

Here is a request sample for adding products to a company:

JSON 
curl --location --request PUT 'https://api-test.sovos.com/v2/configurations/organizations/YOUR-ORG-ID/companies/YOUR-COMPANYID/products' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "items": ["NEW-PRODUCT"]
}'
Response samples

Here is a response sample for creating a company and assigning a product:

JSON 
{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1672405631469,
    "data": {
        "id": "YOUR-COMPANYID",
        "orgId": "YOUR-ORG-ID",
        "taxId": "YOUR-TAXID",
        "legalName": "YOUR-LEGAL-NAME",
        "dba": "YOUR-DOING-BUSINESS-AS-NAME",
        "createdAt": "2022-12-30T13:07:10.8491501Z",
        "createdBy": "user@company.com"
    }
}

Here is a response sample for adding products to a company:

JSON 
{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1687903917359,
    "data": {
        "items": [
            "NEW-PRODUCT"
        ]
    }
}

Error handling

When handling errors, the client application must follow the Indirect Tax API's error handling principles, as specified in the error handling documentation.

In general, all error codes in the 400 range are client errors, which you need to analyze. After fixing the error, you can resend the request. Error codes 408 and 429 are exceptions: In these cases, you should wait at least 60 seconds before retrying. Error codes in the 500 range are server errors. In that case, resend the request according to the instructions given on the error handling documentation, which also includes a full list of error codes Indirect Tax API can return.

Indirect Tax API

Last updated: October 1, 2026