Integration flow

Connect your back end to the Sovos VAT Filing service, from authentication and data import through result download.

The integration runs in two phases. Your back end authenticates and imports transaction data through the Sovos API. Then you review, adjust, and finalize the return in VAT Filing. When the filing is complete, your back end gets the result files. Authenticate each API request with a Bearer token.

Flow steps overview

Prerequisites: Set up accounts and companies so that requests scope to organization, account, and company.
List filings: Send a GET request for available filing periods for account and company. The response includes the filing ID, start and end dates, and related metadata.
Import data: Send a POST request to get an upload URL for the JSON file (filing ID and account or company context). PUT the file, then GET (poll) until the import reaches a terminal state.
Import failure: Sovos stores error files and logs. Use a GET request to import result files to get per-file download URLs (accessUrl), names, and expirations for each file.
Import success: The filing moves to In Progress and redirects to VAT Filing.
In VAT Filing: You run the report (initial values, selected period, and so on). Each manual adjustment can produce new files with updates.
Final report: Final values and detail reports (JSON or CSV) are available, and the filing reaches Complete.
Results: Call a GET request for filing result files to get per-file download URLs (accessUrl), names, and expirations. Download each filing result files before its URL expires.

Note:

For asynchronous notifications and redirect parameters after import, see VAT Filing return flow.

Partner API HTTP errors

These are the typical status codes.

401: Not authenticated. The Bearer token is missing, invalid, or expired.
403: Authenticated but not authorized for the company, filing, import, or operation.
404: The operation declares a missing resource or empty list.
400: On POST request import when the body fails validation.
500: Unexpected upstream or gateway failures. Retry with backoff and include the response uuid when you contact Sovos support.

All REST steps use the contract in openapi.yaml.

Note:

See the API reference.