Onboarding steps overview

Set up your account

Before you can use VAT Filing, Sovos creates your client account using your workspace credentials, a key and a secret. This account gets product IDs and an admin email. Sovos does this step through the API.

Create your company profile

After Sovos sets up your account, you create a company under that account. You specify the company's country, its tax registration number, and other company details. You complete this step through the API.

Get an access token

You use your account's API key and secret to generate an access token. You need this token to authenticate every API call that follows.

Listing available filings

You call the External Partner API to list the filings available for your company. In a non-production environment, this call might return sample data. In production, the response reflects your company's real filings based on its country and configuration.

Upload your transaction files

For a specific filing, you request a time-limited URL. You upload your transaction file, in .xlsx or JSON format, to that URL, and Sovos processes it. If the file has problems, Sovos returns errors so you can fix and re-upload it. If the file is valid, Sovos marks it as complete.

Get your result files

After Sovos processes your file, you can retrieve result files through the API, such as error reports, draft PDFs, and XML files. Each new upload replaces the previous result files for that filing, so only the latest version is available.

Make manual adjustments and finish the filing

If you need to adjust the filing by hand, open the VAT Filing web application using Single Sign On (SSO) through Security Assertion Markup Language (SAML) and the filing ID. There, you can make adjustments, generate draft or final PDFs, and finalize the report. The API always reflects the latest status and files, even after changes made in the web application.

When you trigger a SAML Login, add a state parameter to the request. Apply Base64 encoding to its value before you send it. The decoded value is a JSON object with two fields, page and id, that tell the VAT Filing application which page to open and which filing to load.

For example, { page: 'filing', id: '911' } encodes to &state=eyBwYWdlOiAnZmlsaW5nJywgaWQ6ICc5MTEnIH0=.

Filter your results

You can filter filings and companies by country, date, and report type using query parameters in the API.

Check status updates

You can check status updates, such as file processing or report completion, by polling the API.