POST /v1/indirect-tax/vat-filing/transactions/imports

Use this endpoint to create a transaction import and get a time-limited URL for uploading your JSON file. Make sure the file size matches the metadata.fileSize value from your POST request.

If the filing is already Complete, the endpoint returns 400 with subCode: IMPORT-400-FILING_COMPLETE. You can't import transactions for a closed filing period.

If company.id in the request body doesn't match the company context in your Bearer token, the API returns a 400 error with subCode Filing.CompanyNotFound.

Step 1 - Send a POST request with the required metadata in the request body

Metadata field	Type	Required	Description
company.id	UUID	Yes	Your company ID.
metadata.filename	string	Yes	The name of the JSON file you'll upload.
metadata.fileSize	integer	Yes	File size in bytes. Must be 1 or greater. Must match the actual file you upload.
metadata.contentType	string	Yes	Must be application/json.
metadata.filingId	string	Yes	The target filing ID.
metadata.importProfileId	UUID	Yes	The import profile that defines mapping and validation rules for this upload.

Example request body:

{
  "company": {
    "id": "078be7d7-a1c0-44f8-a2ca-5b23b370d242"
  },
  "metadata": {
    "filename": "transactions.json",
    "fileSize": 1234567,
    "contentType": "application/json",
    "filingId": "911",
    "importProfileId": "078be7d7-a1c0-44f8-a2ca-5b23b370d243"
  }
}

Step 2 - Review the response for the import ID and time-limited upload URL

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "import": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "PENDING"
    },
    "filingId": "911",
    "uploadUrl": "https://s3.amazonaws.com/vf-imports/a1b2c3d4-e5f6-7890-abcd-ef1234567890?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "expirationDate": 1776337200000
  },
  "errors": []
}

Step 3 - Send a PUT request to the uploadUrl

• Set the Content-Type: application/json.

• Provide your JSON transaction file as the body.

PUT {uploadUrl}
Content-Type: application/json

<your JSON transaction file body>

Poll every 30 seconds after uploading your file.

Tip:

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 will cause 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.

GET /v1/indirect-tax/vat-filing/transactions/imports

Use this endpoint to get all transaction imports for a company, with options to filter by status or import ID, and to paginate results.

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

Parameter	Type	Description
companyId	UUID	Filter by company. See the companyId note under List VAT Filings.
importId	UUID	Return only this import record.
status	string	Filter by status. Values: PENDING, PROCESSING, COMPLETED, FAILED.
page	integer	Page number. Minimum 1.
pageSize	integer	Items per page. Range: 1–500.

Step 2 - Review the response

A successful request returns a list of import records and pagination details.

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "COMPLETED",
        "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d242",
        "resultFilesUrl": "https://api.sovos.com/v1/indirect-tax/vat-filing/transactions/imports/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result-files"
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
        "status": "FAILED",
        "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d242",
        "resultFilesUrl": "https://api.sovos.com/v1/indirect-tax/vat-filing/transactions/imports/a1b2c3d4-e5f6-7890-abcd-ef1234567891/result-files"
      }
    ],
    "pageState": {
      "page": 1,
      "perPage": 50,
      "totalPages": 1,
      "totalEntries": 2
    }
  },
  "errors": []
}

GET /v1/indirect-tax/vat-filing/transactions/imports/{importId}

Use this endpoint to get the status or details of a single transaction import record by ID.

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

Parameter	Type	Description
importId	UUID	The import ID returned when you start the import.

Step 2 - Review the response

A successful request returns the import record with its current status and metadata.

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "e4f5a6b7-c8d9-0123-ef45-678901234abc",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d242",
    "resultFilesUrl": "https://api.sovos.com/v1/indirect-tax/vat-filing/transactions/imports/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result-files"
  },
  "errors": []
}

GET /v1/indirect-tax/vat-filing/transactions/imports/{importId}/result-files

Use this endpoint to get time-limited download URLs for the result files attached to a transaction import.

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

Parameter	Type	Description
importId	UUID	The import ID returned when you started the import.

Step 2 - Send a GET request to its accessUrl to download the file before the expirationDate passes

Each file has its own URL and expiration. When an import returns FAILED, result files may include an error log.

Example response (200):

{
  "success": true,
  "status": 200,
  "message": "OK",
  "timestamp": 1776333600000,
  "uuid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "data": {
    "importId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "companyId": "078be7d7-a1c0-44f8-a2ca-5b23b370d242",
    "files": [
      {
        "accessUrl": "https://s3.amazonaws.com/bucket/imports/a1b2c3d4/import-result.json?X-Amz-Expires=3600",
        "name": "import-result.json",
        "expirationDate": 1776340800000
      },
      {
        "accessUrl": "https://s3.amazonaws.com/bucket/imports/a1b2c3d4/error-log.txt?X-Amz-Expires=3600",
        "name": "error-log.txt",
        "expirationDate": 1776340800000
      }
    ]
  },
  "errors": []
}