How the External Partner API works
The External Partner API follows a fixed sequence of steps to authenticate, import, and process your VAT transaction data.
The API connects to Sovos through an Apigee API gateway (the API management layer). The gateway authenticates every request and routes it to the Sovos VAT Filing service. These steps follow a fixed sequence. Each step depends on the previous one completing successfully:
Get the filing period for your company and country using specific identifiers.
Register a transaction import for that filing period. The API returns a time-limited upload URL and an import ID.
Upload your JSON transaction file to the upload URL using an HTTP
PUTrequest.Poll the import status using the import ID until it reaches
COMPLETEDorFAILED.Download result files for the filing or import once processing finishes.
Poll every 5 minutes after uploading your file.
External Partner API responses
Understand response fields, HTTP status codes, and subcodes to handle API responses in your code.
Every API response uses the same StandardEnvelope structure, whether the call succeeds or fails. Each response includes these fields:
| Response element | Type | Description |
|---|---|---|
success | boolean | A flag indicating whether the call succeeded. Always false for error responses. |
status | integer | The HTTP status code. Always equal to the HTTP status code of the response. |
message | string | A short description of the outcome. |
timestamp | integer | The time of the response (Unix epoch ms). |
uuid | string (UUID) | A correlation ID for this response for support tracing. |
data | object | The response payload. |
errors | array | An array of error details ( Always |
Successful response example:
{
"success": true,
"status": 200,
"message": "OK",
"timestamp": 1776333600000,
"uuid": "7c9e2f1a-4b3d-5e6f-7890-abcdef123456",
"data": { ... },
"errors": []
}You can write one response handler for the entire API. Use the uuid field when you contact Sovos support to trace any call.
See API concepts for more on the standard envelope.
Date and timestamps
The External Partner API uses ISO 8601 and Unix epoch milliseconds format to manage the different date field types and timestamps.
ISO 8601 dates
The External Partner API uses ISO 8601 dates for the envelope IsoDate to note filing period date boundaries and date filters. startDate,endDate, dueDate, and their query parameter equivalents use this format.
Format: YYYY-MM-DD (UTC, no time component)
Example: 2019-03-12
startDateandendDate- Time boundary of the filing's reporting period.
dueDate- Deadline for submitting the filing to the tax authority.
expirationDate- Date when a presigned upload or download URL expires.
Timestamps
The API uses timestamps for the envelope timestamp (Unix epoch milliseconds, UTC) field and presigned URL expirationDate fields. expirationDate also appears as a query parameter on GET /filings, where it filters results by expiration timestamp rather than marking a URL's expiry.
Type: 64-bit integer (
int64)Example: 1776333600000
Using the wrong date format causes silent filtering errors or upload failures.
Pagination
Use pagination parameters to control how many results list endpoints return.
Use the page and pageSize query parameters to control which results you get.
| Parameter | Description | Type | Default | Max |
|---|---|---|---|---|
page | The page number to return. Starts at 1. | integer | 1 | - |
pageSize | The number of items per page. | integer | 50 | 500 |
Pagination response
Every paginated response includes a pageState object with these fields:
page- Current page number
perPage- Items returned on this page
totalPages- Total number of pages
totalEntries- Total number of records across all pages
Example of a paginated response:
"pageState": {
"page": 1,
"perPage": 50,
"totalPages": 3,
"totalEntries": 120
}To get all records, iterate requests until page equals totalPages.
Filtering
Two endpoints support filtering: List VAT filings and List transaction imports. Add one or more filter parameters to your request to narrow the results. All filter parameters are optional.
Both endpoints also support pagination, which lets you control how many results a request returns.
Filing filters
Use these parameters on the List VAT filings endpoint:
| Parameter | Description | Example |
|---|---|---|
companyId | Returns filings for this company only. Include it in most requests. | 078be7d7-a1c0-44f8-a2ca-5b23b370d242 |
country | Returns filings for this country name. | Hungary |
countryCode | Returns filings for this ISO 3166-1 alpha-2 country code. | HU |
returnType | Returns filings for this return or report type. | VAT |
startDate | Returns filings with a period start date on or after this date. | 2019-01-01 |
endDate | Returns filings with a period end date on or before this date. | 2019-03-31 |
dueDate | Returns filings with this due date. | 2019-03-12 |
expirationDate | Returns filings with this expiration timestamp. | 1776333600000 |
See Date and timestamps for the date and timestamp formats these parameters use.
Transaction import filters
Use these parameters on List transaction imports:
| Parameter | Description | Example |
|---|---|---|
companyId | Returns imports for this company only. | 078be7d7-a1c0-44f8-a2ca-5b23b370d242 |
importId | Returns only the import that matches this ID, if it's visible to your token. | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
status | Returns imports with one of these statuses:
| COMPLETED |