About the External Partner API
The External Partner API connects your systems to Sovos so you can automate your VAT return workflows.
The External Partner API lets you get filing periods, submit transaction data files, and track processing, all from your own systems. To get started with the External Partner API, you need a valid Bearer token, your company Sovos ID, and an import profile ID.
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. The API returns a time-limited upload URL. Upload your JSON transaction file to that URL, then poll the import status until it reaches a terminal state, either
COMPLETED, orFAILED.- Downloading result files
Get time-limited download links for files attached to a completed filing or import. For failed imports, result files include error logs to help you identify and fix the problem.
Base URL
All endpoints use these 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.
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. 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. For successful imports and completed filings, they contain processing data and output files. For failures, they contain error logs. You download them using time-limited URLs.
- Time-limited URLs
- Both upload URLs and download URLs have expiration dates. The API returns this date when you register the import. Upload and download your files and result files before they expire. Time-limited URLs 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:
success,status,message,timestamp,uuid,data, anderrors.
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. 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 (for example, Hungary) and an ISO 3166-1 alpha-2 code (for example, HU).
- Report type
- The kind of tax return a filing represents, for example VAT.
Resources
Find the base URLs for the External Partner API and an overview of its endpoints.
Base URL
All endpoints use these 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 two groups: filings and transaction imports. This table lists each endpoint and what it covers. For the exact schema name and structure of any request or response object, including envelope schemas like FilingsListEnvelope or TransactionImportCreateEnvelope, see the OpenAPI reference.
| 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 URLs 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 URL. | |
| 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 URLs for a transaction import's result files. |