Data upload

Check filing status before importing

Before you start a transaction import, check that the target filing has a Preparation status. Filings in the In Progress or Complete status don't accept imports. If the filing is Complete, the API returns a 400 error with subcode IMPORT-400-FILING_COMPLETE.

Use GET /v1/indirect-tax/vat-filing/filings/{filingId} to confirm the status before calling the import endpoint.

Uploading files with the uploadURL

The uploadUrl is a time-limited URL. Send your PUT request directly to S3, not to the Sovos API. Don't include an Authorization header. The time-limited URL carries its own authentication. Adding an Authorization header to the PUT request causes it to fail.

If you send a new transaction import for a filing that's still in Preparation status, Sovos deletes the earlier import's data and replaces it with the new import's data. The most recent import is always the source of truth for that filing period. There's no conflict or rejection if you submit more than one import for the same filing.

Upload files before the time-limited URL expires

The uploadUrl the API returns when you start an import expires 10 minutes after the API returns it. If you miss the window, start a new import to get a fresh URL.

Don't store the upload URL for later use. Generate the URL immediately before you upload, and upload it right away.

Set the Content-Type header

Set the Content-Type header to application/json and make sure the file size matches the metadata.fileSize value you sent in the POST request.

Processing and monitoring

After you upload your file, poll GET /v1/indirect-tax/vat-filing/transactions/imports/{importId} every 30 seconds to check the import status. Keep polling until the status reaches COMPLETED or FAILED.

Result files

Download URLs for result files expire 10 minutes after the API returns them. Each file has its own accessUrl and expirationDate. Check the expiration date before downloading, and call the result files endpoint again if a URL has expired.

Sovos deletes filing result files 30 days after the filing reaches Complete. Download and store any filing result files you need before that window closes.