Filings

Filings track VAT return periods by country and company, each with a lifecycle status that determines whether you can import transaction data.

A filing represents a VAT return period for a specific country and company. Each filing has a start date, end date, due date, and a FilingStatus. The status determines what you can do with the filing in the VAT return cycle.

Note:

See API concepts for definitions of key terms used on this page.

Filing statuses


Status	Meaning	Can you import transactions?
`Preparation`	The period is open and ready for data. This is the initial state of a return.	Yes
`In Progress`	Sovos is processing the filing submission.	No
`Complete`	The period has ended. The filing moves to `Complete` when you click Mark as complete in VAT Filing.	No. The API returns 400.

Important:

The resultFilesUrl field is always included in the filing response, regardless of status. Files are only available once the filing reaches Complete status. Calling this URL while the filing is in Preparation or In Progress returns 404

Filing status lifecycle

A filing moves through three stages:

Preparation: The filing is open and ready to accept transaction data.
In Progress: Sovos is processing the filing submission. The filing moves there automatically once the import completes.
Complete: The period has ended. Click Mark as complete in VAT Filing to move the filing to this status.

Corrections and resubmissions

The External Partner API doesn't support reopening a Complete filing, and it doesn't support corrections, amendments, or supplementary returns for a filing that's already Complete.

If you need to change data after a filing reaches the Complete status, start a new return for a new filing period instead.

Self-correction in a later return is allowed where VAT due is under €6,000. Above this threshold, you may need an amended return or a supplementary return depending on your circumstances. Contact Sovos to discuss your options.

List VAT filings

GET /v1/indirect-tax/vat-filing/filings

Use this endpoint to get all VAT filing periods for a company, with options to filter by country, date range, or return type.

Step 1 - Send a GET request with the appropriate query parameters

All query parameters are optional.


Parameter	Type	Description
`companyId`	UUID	Filter by company ID. Include it in most requests to filter results to a specific company.
`country`	string	Filter by country name. Example: Hungary.
`countryCode`	string (2 chars)	Filter by ISO 3166-1 alpha-2 code. Example: HU.
`returnType`	string	Filter by return type. Example: VAT.
`startDate`	date	Return filings with period start on or after this date using the YYYY-MM-DD format.
`endDate`	date	Return filings with period end on or before this date using the YYYY-MM-DD format.
`dueDate`	date	Filter by filing due date using the YYYY-MM-DD format (UTC).
`page`	integer	Page number. Minimum 1.
`pageSize`	integer	Items per page. Range: 1-500.
`expirationDate`	integer	Filter filings by expiration date timestamp. Unix epoch milliseconds timestamp (int64).

Note:

See the Date and timestamps page for more information about date formatting.

Step 2 - Review the response

A successful request returns a list of filing periods and pagination details.

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "7c9e2f1a-4b3d-5e6f-7890-abcdef123456",
  "data": {
    "items": [
      {
        "id": "911",
        "country": "Hungary",
        "countryCode": "HU",
        "dueDate": "2019-03-12",
        "startDate": "2019-01-01",
        "endDate": "2019-03-31",
        "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d245",
        "reportType": "VAT",
        "reportName": "HU VAT return Q1",
        "importProfileId": "078be7d7-a1c0-44f8-a2ca-5b23b370d243",
        "status": "Preparation",
        "resultFilesUrl": "https://api.sovos.com/v1/indirect-tax/vat-filing/filings/911/result-files"
      }
    ],
    "pageState": {
      "page": 1,
      "perPage": 50,
      "totalPages": 3,
      "totalEntries": 120
    }
  },
  "errors": []
}

Important:

Note:

See the API reference.

Response codes

200: Returns a list of filings and pagination state.
401: Unauthorized.
403: Forbidden.
404: No filings match the filters, or the company has no filings.
500: Server error.

Get a filing

GET /v1/indirect-tax/vat-filing/filings/{filingId}

Use this endpoint to view a single filing by its ID.

Step 1 - Send a GET request with the required path parameter


Parameter	Type	Example	Description
`filingId`	string	911	The filing ID. This parameter is a plain string, not a UUID. Use the value from the `id` field in a filing record.

Step 2 - Review the response

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "8d0f3a2b-5c4e-6f70-8901-bcdef2345678",
  "data": {
    "id": "911",
    "country": "Hungary",
    "countryCode": "HU",
    "dueDate": "2019-03-12",
    "startDate": "2019-01-01",
    "endDate": "2019-03-31",
    "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d245",
    "reportType": "VAT",
    "reportName": "HU VAT return Q1",
    "importProfileId": "078be7d7-a1c0-44f8-a2ca-5b23b370d243",
    "status": "Complete",
    "resultFilesUrl": "https://api.sovos.com/v1/indirect-tax/vat-filing/filings/911/result-files"
  },
  "errors": []
}

Important:

Response codes

200: Returns the filing.
401: Unauthorized.
403: Forbidden.
404: Filing not found, or not visible to your token.
500: Server error.

Note:

See the API reference.

Get filing result files

Important:

Download URLs expire 10 minutes after the API returns them.

GET /v1/indirect-tax/vat-filing/filings/{filingId}/result-files

Use this endpoint to get time-limited download URLs for the result files attached to a specific filing ID.

Note:

See API concepts for more information on time-limited URLs.

Step 1 - Send a GET request with the required path parameter


Parameter	Type	Example	Description
`filingId`	string	911	The filing ID. This parameter is a plain string, not a UUID. Use the value from the `id` field in a filing record.

Step 2 - Download each result file from its access URL before the expiration date

To download a file, send a GET request to its accessUrl before the expirationDate passes. Each file has its own URL and expiration.

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "9e1a4b3c-6d5f-7081-9012-cdef34567890",
  "data": {
    "filingId": "911",
    "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d245",
    "files": [
      {
        "name": "filing-result.xml",
        "accessUrl": "https://s3.amazonaws.com/bucket/prefix/filing-result.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600",
        "expirationDate": 1776337200000
      },
      {
        "name": "validation-report.pdf",
        "accessUrl": "https://s3.amazonaws.com/bucket/prefix/validation-report.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600",
        "expirationDate": 1776337200000
      }
    ]
  },
  "errors": []
}

The result files are available once the filing is Complete. Sovos deletes result files 30 days after the filing reaches Complete.

Response codes

200: Returns a list of files with download URLs.
401: Unauthorized.
403: Forbidden.
404: No result files exist for this filing, or the filing isn't visible to your token.
500: Server error.

Note:

See the API reference.

How can we help?

Filings

Filing statuses

Filing status lifecycle

Corrections and resubmissions

List VAT filings

Response codes

Get a filing

Response codes

Get filing result files

Response codes

sovos-footer