Transaction imports

Transaction imports let you upload JSON transaction data into a filing period.

To submit transaction data for a filing period, you upload a JSON file using a two-step process.

Send a POST request to register the import. The API returns a time-limited upload URL.
Send a PUT request to that URL with your JSON transaction file as the request body.

You must complete the upload before the expirationDate.

Note:

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

Import statuses

These are the current import statuses. Sovos may add more in a future release.


Status	Meaning	Result files available?
PENDING	Sovos registered the import and it's waiting for you to upload the file.	No
PROCESSING	Sovos received the file and is processing it.	No
COMPLETED	Sovos finished processing the file successfully. Result files are ready.	Yes
FAILED	The import failed. Result files include error logs.	Yes. Check for error logs.

Tip:

A filing's resultFilesUrl is always present in the response regardless of status. An import's resultFilesUrl is only available once the import reaches COMPLETED or FAILED status.

Request a transaction import

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.

Note:

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

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:

JSON

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

{
  "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):

JSON

{
  "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": []
}

{
  "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.

JSON

PUT {uploadUrl}
Content-Type: application/json

<your JSON transaction file body>

PUT {uploadUrl}
Content-Type: application/json

<your JSON transaction file body>

Poll every 30 seconds after uploading your file.

Tip:

See Best practices for more details about using uploadURL.

Response codes

200: Returns the import ID, status, and time-limited upload URL.
400: Bad request. Check errors[].subCode. Common cause: the filing is already Complete. IMPORT-400-FILING_COMPLETE) or company.id doesn't match your bearer token's company context (Filing.CompanyNotFound).
401: Unauthorized.
500: Server error.

Note:

See the API reference.

List transaction imports

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):

JSON

{
  "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": []
}

{
  "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": []
}

Response codes

200: Returns a list of import records and pagination state.
401: Unauthorized.
403: Forbidden.
404: No imports exist for this company.
500: Server error.

Note:

See the API reference.

Get a transaction import

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):

JSON

{
  "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": []
}

{
  "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": []
}

Response codes

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

Note:

See the API reference.

Get import result files

Important:

Download URLs expire 10 minutes after the API returns them.

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):

JSON

{
  "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": []
}

{
  "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": []
}

Response codes

200: Returns a list of files with download URLs.
401: Unauthorized.
403: Forbidden.
404: No result files available for this import.
500: Server error.

Note:

See the API reference.