Searching for invoices

The following diagram gives a detailed overview of the process for searching invoices:

Overview process for searching invoices.

Step 1: Client Sends GET Request

It's possible to search the archive for invoice references and related data using filters. To retrieve a stored invoice, send a GET request to the /v2/archived-documents endpoint.

To make this request, set the following query parameters:


Name	Type	Required	Default	Description
documentNumber	string	No		Set it to the document number.
documentDate	string	No		Set it to the document date.
supplierName	string	No		Set it to the supplier's name.
supplierAuthority	string	No		Set it to the supplier's countryCode.
supplierIdentifier	string	No		Set it to the supplier's tax ID.
buyerName	string	No		Set it to the buyer's name.
buyerAuthority	string	No		Set it to the buyer's countryCode.
buyerIdentifier	string	No		Set to the buyer's tax ID.
page	integer	No	1	Set it to the page to be returned.
perPage	integer	No	10	Set the maximum number of hits to be included in the result.

Request Sample

curl --location --request GET 'https://api-test.sovos.com/v2/archived-documents?documentNumber=240&documentDate=2021-06-16&supplierName=EARCHIVINGQATEST&supplierAuthority=IN&supplierIdentifier=123456789&buyerName=EARCHIVINGQATEST&buyerAuthority=IN&buyerIdentifier=123456789&page=1&perPage=50' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response Sample

{
  "timestamp": "1699458506",
  "success": true,
  "status": 200,
  "message": "Documents Listed",
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 50,
      "totalEntries": 2,
      "totalPages": 1
    },
    "items": [
      {
        "documentId": "c259cda4f9a6d007a5e1bd3cd3fd656d"
      },
      {
        "documentId": "12312424fewfsd07a5e1bd3cd3fd656d"
      }
    ]
  }
}

Step 2: Sovos Returns Invoice (+ Attachments and Metadata)

As a response, Sovos returns the list of references of the documents that were initially sent to Sovos.

Error Handling

The client must apply the error handling principles that are outlined on the responses page. The responses page also includes a full list of error codes that the API might return.

In general, all error codes in the 400 range are client errors that the client must analyze. After fixing the errors, the client can resend the request. For 408 and 429 errors, the client must wait 60 seconds before resending the request.

Error codes in the 500 range are server errors. The client should resend the request according to the instructions on the responses page.

Sovos Docs

Searching for invoices

Step 1: Client Sends GET Request

Step 2: Sovos Returns Invoice (+ Attachments and Metadata)

Error Handling

sovos-footer