Filing

About the External Partner API

The External Partner API helps you connect your systems to Sovos, so you can prepare and submit VAT returns automatically.

The External Partner API is the VAT filing implementation of the Sovos Indirect Tax API. Use it to get filing periods, send data files, and track processing from your own systems.

Use cases

Managing filing periods

Get VAT filing periods for your company, including completed ones. Filter by country, date range, or return type. Check a filing's status to know whether it's ready to accept data, in progress, or complete.

Uploading transaction data

Register a transaction import for a specific filing period using JSON transaction files in the link. The API returns a time-limited upload link you can use later. Then you can poll the import status until it reaches a terminal state.

Downloading result files

Get time-limited download links for files attached to a completed filing or import. For failed imports, the result files include error logs to help you find and fix the problem.

Checking service status

Check whether the API is available before you send filings or imports. For more information, see Service status.

External Partner API concepts

General concepts

Error subcode
A stable, machine-readable string in every error response that identifies the specific cause of a failure. You use it in your error-handling logic. Unlike the human-readable message field, it doesn't change between API versions.
Import profile
A Sovos configuration that defines how Sovos maps and validates your JSON transaction file. You supply the import profile ID when you register a transaction import and Sovos sets it up for you.
Import status
The stage your transaction is currently at: PENDING, PROCESSING, COMPLETED, or FAILED. You poll this import status using the import ID to know when processing finishes and result files are ready.
Result files
The output files Sovos generates after processing a filing or import and that you can download using time-limited links. For successful imports and completed filings, they contain processing data and output files. For failures, they contain error logs.
Time-limited links
Both upload and download links have expiration dates, so you should upload and download your files and result files before they expire. The API returns the expiration date when you register the import. Time-limited links are available for 10 minutes after the API generates them.
Standard envelope
The consistent response wrapper that every API endpoint returns, whether the call succeeds or fails. It always contains the same seven fields.

Filing-specific concepts

Filing
A VAT return period for a specific country and company. Each filing has a start date, end date, due date, and a status that controls whether you can import transaction data for it.
Filing status
The stage a filing is in during its lifecycle: Preparation, In Progress, or Complete. Preparation is the filing's initial state and the only status where you can import transactions.
Filing ID
The unique identifier for a filing. Use it to get a single filing, get its result files, or start a transaction import for it.
Country and country code
The country a filing applies to, shown as both a display name such as Hungary and an ISO 3166-1 alpha-2 code such as "HU".
Report type
The kind of tax return a filing represents. Example: "VAT".

Resources

Base URL

All endpoints use the following servers and base URLs.

Location Server Path prefix
Global https://api.sovos.com /v1/indirect-tax/vat-filing/
US https://api-us.sovos.com /v1/indirect-tax/vat-filing/
Note:

The base URL of the User Acceptance Testing (UAT) environment is https://api-test.sovos.com.

Endpoint overview

The External Partner API organizes its endpoints into three groups.

Topic Endpoint Path What it covers
Filings List VAT filings GET /v1/indirect-tax/vat-filing/filings Get a filtered list of filings for your company.
Get a filing GET /v1/indirect-tax/vat-filing/filings/{filingId} Get a single filing by its ID.
Get filing result file links GET /v1/indirect-tax/vat-filing/filings/{filingId}/result-files Get download links for a filing's result files.
Transaction imports List transaction imports GET /v1/indirect-tax/vat-filing/transactions/imports Get a filtered list of transaction imports for your company.
Start a transaction import POST /v1/indirect-tax/vat-filing/transactions/imports Register a transaction file and get a presigned upload link.
Get a transaction import GET /v1/indirect-tax/vat-filing/transactions/imports/{importId} Get a single transaction import by its ID.
Get import result file links GET /v1/indirect-tax/vat-filing/transactions/imports/{importId}/result-files Get download link for a transaction import's result files.
Service status Get a service status GET /v1/indirect-tax/vat-filing/status Check whether the API is available.

For the exact schema name and structure of any request or response object, including envelope schemas such as FilingsListEnvelope or TransactionImportCreateEnvelope, see the External Partner API reference.