Searching for invoices

Learn how to retrieve invoices from the archive using reference IDs and explore the available endpoints and query parameters for efficient searching.

Invoices can be retrieved from the archive by using a referenceId. These referenceId values can be searched for by sending a GET request to the /archived-documents or the /archived-documents/{companyId}/references endpoints. Both endpoints allow using several query parameters to make a search.

GET /archived-documents

This endpoint allows searching the archive for invoice references and associated metadata, based on several filter criteria.

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 it 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.

Note:

See the API Specifications page for more information about this request. In addition, there are full samples on the Postman Samples page.

Request sample

curl --location --request GET 'https://api-test-tls.sovos.com/v1/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": 1625046587920,
    "status": 200,
    "success": true,
    "message": "Invoices listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "moreResults": "false"
        },
        "items": [
            {
                "Reference": "ca52a2492acf471983c6f66ca38ac712",
                "Document": {
                    "DocumentFormat": "INIDJSON",
                    "ExplicitAuditDataInfo": {
                        "SignatureFormat": "INJWS",
                        "AuditCategory": "NotSpecified"
                    }
                },
                "InvoiceInfo": {
                    "InvoiceNo": 240,
                    "InvoiceDate": "2021-06-16T00:00:00",
                    "OriginalInvoiceNo": 1234555,
                    "PurchaseOrderNos": {
                        "PurchaseOrderNo": [
                            "0123",
                            4567
                        ]
                    }
                },
                "SupplierInfo": {
                    "Name": "EARCHIVINGQATEST",
                    "StoreFor": "true",
                    "CountryCode": "IN",
                    "VatNo": 123456789
                },
                "BuyerInfo": {
                    "Name": "EARCHIVINGQATEST",
                    "StoreFor": "false",
                    "CountryCode": "IN",
                    "VatNo": 123456789
                },
                "Attachments": {},
                "CustomProperties": {
                    "Property": {
                        "Name": "TestCategory",
                        "Value": "Test23"
                    }
                },
                "CustomNumericProperties": {
                    "Property": {
                        "Name": "Test",
                        "Value": 1234
                    }
                },
                "StoredTime": "2020-12-12T21:44:48Z",
                "StoragePeriodEndDate": "2030-06-16T00:00:00"
            }
        ]
    }
}

GET /archived-documents/{companyId}/references

This endpoint allows listing all invoice references within a specified company.

To make this request, set the following parameters:


Name	Type	Required	Parameter Type	Description
companyId	string	Yes	Path	Set it to the companyId of the company that contains the invoices that must be retrieved.
perPage	integer	Yes	Query	Set it to the maximum number of hits to return.
page	integer	Yes	Query	Set it to the page to be returned.
expiring	boolean	No	Query	Set it to true for the search to only include invoices that will expire within the chosen date range.
startDate	string	No	Query	Set the start date of the range.
endDate	string	No	Query	Set the end date of the range.
includeInvoicesWithExplicitExpiryDate	boolean	No	Query	Set it to true for the search to include invoices with a custom storage period end date.

Note:

See the API Specifications page for more information about the request. In addition, there are full samples on the Postman Samples page.

Request sample

curl --location --request GET 'https://api-test-tls.sovos.com/v1/archived-documents/{companyId}/references?perPage=100&page=1&expiring=true&startDate=2029-06-03&endDate=2029-06-05&includeInvoicesWithExplicitExpiryDate=false' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "success": true,
    "status": 200,
    "message": "References listed",
    "timestamp": 1605708449978,
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 100,
            "moreResults": "false"
        },
        "items": [
            "787345e85849458dbda2da4e5dbd86f9",
            "73631be9dfe1483ea41ac2e446119a69",
            "c0d8e70fe2c647a286194022f02da4d7",
            "d78cf5f61d7f41cda3546fd6a0c8194c",
            "39615e31946f4d74a776e211ee9fecb7",
            "64fd5b83e2b34480829dca26bc2c88b3",
            "dfcafdc20a27427ca88675426cc7c6a4"
        ]
    }
}

Search Algorithm

If there are more invoices in the company than the perPage parameter allows, the invoices need to be searched with a sequential algorithm. An example of such algorithm is provided below:

Initially, the client application sends the GET request with the following parameters: perPage=<the maximum number of hits to be returned, for example 1000>, page=1.
The output is a list of references, starting from the beginning of the company. This list of references can also be viewed as the first "page". If the parameter moreResults=true, then there are more references in the company.
The client sends another request with the following parameters: perPage=<the maximum number of hits to be returned, for example 1000>, page=< the perPage value multiplied by X, where X is the number of iterations; for example, page should be set to 1000 for the first iteration, 2000 for the second iteration, etc.>.
The output is the next list of references, starting from the specified page (for example, 1000 for the first iteration, 2000 for the second iteration, etc.) of the company. This list of references can also be viewed as the next "page" in the sequence of iterations. If the parameter moreResults=true, then there are more references in the company.
The client repeats steps 3 and 4 until the output contains "moreResults=false".

Error Handling

Adhere to the error handling principles outlined on the responses page.

In general, all error codes in the 400 range are client errors, so analyze them individually. After fixing the erorr, it's possible to resend the request. Error codes 408 and 429 are exceptions: in these cases, you should wait at least 60 seconds before retrying. The error codes in the 500 range are server errors. In that case, you need to resend the request, according to the instructions given on the responses page, which also includes a full list of error codes the COAPI can return.

Sovos Docs

Searching for invoices

GET /archived-documents

GET /archived-documents/{companyId}/references

Search Algorithm

Error Handling

sovos-footer