Sovos.com Contact Support

e-invoicing

Indirect Tax API

Configuration

Learn how to configure eArchiving services by setting up a company and authorizing it for archiving through API requests.

Before getting started with Sovos eArchiving services, you must send a few API requests to set up a company and authorize it for archiving in our backend.

An overview of the configuration process is shown in the diagram below:A diagram showing client and Sovos interactions

Step 1: Create New Company

All parties that send or receive invoices are referred to as Invoicing Parties. To create an Invoicing Party in Sovos eArchive, the client application performs a POST request to the /config/{countryCode}/companies endpoint.

Invoices cannot be stored for an Invoicing Party. The Invoicing Party exists as either just a trading partner (without archiving capabilities), or it can become a User Organization (with archiving capabilities) at a later stage (see step 2).
Note:

If you don't know all the buyers and/or suppliers in advance, or don't want to register all of them as invoicing parties, you can only register the entities that actually store invoices in Sovos eArchive.

The following design considerations for the request parameters should be taken into account:
countryCode

The countryCode parameter must be set in the request for a legal entity's country of establishment to be taken into account when calculating the storage period for the invoice. Hence, the countryCode value determines the storage period. The value of the countryCode parameter must be an ISO 3166-1 alpha-2 country code.

You'll need to implement a filtering function, so that the countryCode parameter can only be set to a country code that's supported by Sovos eArchive.
Note:

Once a country code has been set, it cannot be changed.

Note:

If there are Hungarian or Italian legal unit(s) for which the countryCode parameter is set to "HU" or "IT", then the Hungarian or Italian e-invoices must be stored in this section. This is required for the Hungarian and Italian preservation (time-stamping) processes.

companyId
The companyId parameter in the request should be a unique identity of an Invoicing Party you have defined, e.g., an existing identity number within your e-invoicing network.
Note:

The companyId shouldn't contain any white spaces.

name
The name parameter in the request should be the full name of the legal entity for which the company is created.
Note:

See the API Specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample

JSON 
curl --location --request POST 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
    "companyId": "CompanyX",
    "name" : "Company X Ltd."
}'
Response sample
JSON 
{
    "success": true,
    "status": 200,
    "message": "Company created",
    "timestamp": 637274678557640000,
    "data": {}
}

Step 2: Enable Company

After creating a company, the client application must send a PATCH request to the /config/{countryCode}/companies/{companyId} endpoint to enable the company for storage. Once the company is enabled, the Invoicing party becomes a User Organization.

This request call's response contains the URL to the Sovos eArchive GUI and a SuperAdmin username and password (Archive GUI credentials). For more information, see the Sovos eArchive GUI page.

To make this request, set the following parameters:
Name Type Required Parameter Type Description
countryCode string Yes Path Set it to the same country code used in step 1.
companyId string Yes Path Set it to the company ID of the company registered in step 1.
status string Yes Request body Set it to "Enabled".
Note:

See the API Specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample
JSON 
curl --location --request PATCH 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--data-raw '{
	"status": "Enabled"
}'
Response sample
JSON 
{
    "success": true,
    "status": 200,
    "message": "Company Enabled",
    "timestamp": 1603098455907,
    "data": {
        "superAdminUsername": "SuperAdmin",
        "superAdminPwd": "kpK5We",
        "companyPath": "/archive/CompanyGroup/CompanyXYZ"
    }
}

Maintenance of Companies

There are several API endpoints available for maintaining and monitoring all created companies:
Reset Company Password

In case the SuperAdmin credentials have been lost, it's possible to send a POST request to the /config/{countryCode}/companies/{companyId}/reset-password endpoint with the input parameters countryCode and companyId. This request call returns a new password for the SuperAdmin user of the given company.

To make this request, set the following path parameters:
Name Type Required Description
countryCode string Yes Set it to the same country code used in step 1.
companyId string Yes Set it to the company ID of the company registered in step 1.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample
JSON 
curl --location --request POST 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}/reset-password' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'
Response sample
JSON 
{
    "success": true,
    "status": 200,
    "message": "Password Reset",
    "timestamp": 1603099522229,
    "data": {
        "superAdminPwd": "o7KHFy"
    }
}
List Companies

To obtain a list of all registered companies, it's possible to send a GET request to the /config/{countryCode}/companies endpoint. This gives an overview of all companies registered in your area.

To make this request, set the following parameters:
Name Type Required Parameter Type Description
countryCode string Yes Path Set it to the country code, as specified by the ISO 3166-1 alpha-2 standard.
perPage integer Yes Query Set it to the maximum number of hits to return.
page integer Yes Query Specifies the starting point of the hits to be returned.
Note:

Although the country code is specified in the path, the output is a list of all the companies created in your area, so it doesn't return, for example, only Indian companies.

Note:

See the API specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample
JSON 
curl --location --request GET 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies?perPage=2&page=1' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'
Response sample
JSON 
{
    "success": true,
    "status": 200,
    "message": "Companies Listed",
    "timestamp": 1602770463414,
    "data": {
        "pageState": {
            "page": "1",
            "perPage": "2",
            "moreResults": "true"
        },
        "items": [
            {
                "name": "CompanyX"
            },
            {
                "name": "CompanyY"
            }
        ]
    }
}
Get Company Information

This endpoint can be used to retrieve information from a given company. Send a GET request to the /config/{countryCode}/companies/{companyId} endpoint.

To make this request, set the following path parameters:
Name Type Required Description
countryCode string Yes Set it to the country code, as specified by the ISO 3166-1 alpha-2 standard.
companyId string Yes Set it to the company ID of the company registered in step 1.
Note:

See the API specifications page for more information about the request.

Below is a sample request and response. In addition, there's a full sample request and response on the Postman Samples page.

Request sample
JSON 
curl --location --request GET 'https://api-test-tls.sovos.com/v1/config/{countryCode}/companies/{companyId}' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'
Response sample
JSON 
{
    "success": true,
    "status": 200,
    "message": "Company Returned",
    "timestamp": 1602771739509,
    "data": {
        "metadata": {
            "archivePath": "/archive/CompanyX/08AAACI9260R002",
            "storageInfo": {
                "friendlyName": "Company X Ltd.",
                "countryOfEstablishment": "IN"
            },
            "status": "Registered"
        }
    }
}

Error handling

Follow the error-handling principles outlined on the Responses page.

In general, all error codes in the 400 range are client errors and must be analyzed individually. After fixing the error, you can try to resend the request. The error codes 408 and 429 are exceptions, in which cases you must wait 60 seconds before retrying.

The error codes in the 500 range are server errors. In that case, you should retry the request according to the instructions on the Responses page, which also includes a full list of error codes that COAPI may return.

Last updated: October 1, 2026