Searching for Invoices

Use a variety of search criteria to find a specific invoice.

The External API (XAPI) allows for the searching of invoices. The search is fairly rich in features offering the following key features:

  • Ability to use a wide variety of search criteria.
  • Ability to specific what fields are returned.
  • Ability to query the API to find out what search options are available.

Search Basics

There are some key components required by searches:

  1. All searches require a valid token.
  2. Searches return paged data in order to prevent transport delays and disruptions. It is recommended that a developer uses Postman to determine the best page size for them. Paging is covered more below.
  3. All search results are returned as JSON strings. If Postman is used, the sample Postman Collection contains a visualizer that places the results into a table for quick debugging.

Below is a summary of the Postman UI for Invoice Searching:

Determining the Search Criteria

The values that may be used in the search criteria are dynamic and can change over time. This is because companies add and remove lookup codes as needed. To view the list of what options are available an endpoint was provided to assist with this.

Endpoint: GET {{protocol}}://{{BaseUrl}}/api/{{Version}}/invoicing/search/InvoiceSearchRequest

This endpoint will return every option available in the search request. For example:

#!json
{
    "paging": {
        "pageSize": 100,
        "pageStartId": 0
    },
    "query": {
        "invoiceStatus": [
            "COMMITTED",
            "FINISHED",
            "NOT POSTED",
            "OPEN",
            "PROCESSING"
        ],
        "invTypeCode": [
            "AA","BB","CC" ...
        ],
        "jobStatusCode": [
            "CONFIRMED",
            "CANCELLED",
            "LOST",
            "WON", ...
        ],
        "paymentTypeCode": [
            "AMEX", ...
            ],
        "saleReferralCode": [
            "ONLIN",
            "PHONE",
        ],
        "modifiedStartDateTime": "2020-12-01T00:00:00",
        "modifiedEndDateTime": "2020-12-01T00:00:00"
    },
    "tables":{...}
}

Customizing which Fields are Returned.

The search criteria allows the calling application to also reduce the number of fields returned. This is accomplished by completing the “tables” section in the request. Using the same API method as outlined above the available list of fields can be determined.

Below is an example of a search where a reduced set of fields are used. Note, field collections using “null” or empty arrays “[]” both indicate that all fields will be returned.

#!json
  ..."tables": {
        "Invoice": [
            "Code",
            "ID",
            "BillToFirstName",
            "BillToLastName",
            "InvoiceTotal",
            "sysModified"
        ],
        "InvoiceNote": [
            "ID",
            "Code",
            "Note"
        ],
        "InvoiceAddress": [
            "InvoiceCode"

        ],
        "InvoiceComment": [
            "InvoiceCode",
            "CommentCode",
            "CommentDesc",
            "InPackage"
        ],
        "InvoiceMisc": null,
        "InvoiceLabor": null,
        "InvoiceItem": null,
        "InvoiceModel": null,
        "InvoiceSerial": null,
        "InvoiceTax": null,
        "InvoicePayment": null,
        "InvoiceWarranty": null,
        "InvoiceWarrantyDetail": null,
        "InvoicePackage": null
    }

Paging

Paging is a core component of any searching endpoints provided by the XAPI. Paging is provided to prevent overconsumption of resources for a single query, and to allow the calling application to control their response speed to payload size ratio.

Each time a search is executed it returns an indicator which informs the calling application whether or not there are more records after this page.

For example, if search was to return 1,000 rows and the page size was set to 100, the calling application end up calling the endpoint 10 times in order to return all 1,000 rows of data. Below is an example of the JSON request paging section:

#!json
{
   "paging": {
        "pageSize": 100,
        "pageStartId": 0
    },
    ...

The results of this query will return the highest unique record key on this given page, as well as provide a Boolean value indicating if there are more pages.

#!json
{
  "Results": {
    "Success": true,
    "Message": "Returned 100 records",
    "LastException": null
  },
  "Paging": {
    "PageSize": 100,
    "LargestID": 271620,
    "PagesRemaining": true
  },,
    ...

In the above example, the next query would simply issue the request again except change the starting page ID:

#!json
{
   "paging": {
        "pageSize": 100,
        "pageStartId": 271620
    },
    ...