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
messagefield, 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, orComplete.Preparationis 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/ |
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.
