Search Requests

Beginning with v4 of the API Search requests have now been updated to use a POST route using the payload of the body to contain the search criteria.

Many times you will need to filter and sort your data. For example, you might want all the invoices belonging to a specific account ordered by date. To do this you need to use the “/Search” route. Search requests allow you to filter and sort the returned data on one or more properties of the object. The basic forumula for the search request is:

A top value: limiting results to a specific value in the range 1 to 10000
- if not specified the default top value will be 100
- the searchable API has removed the ability to request all records (aka top 0) and limits results to an upper bound of 10000
A search array that can be conceptualized as where clauses.
A condition which logically joins the filter array with the orderby array using a logical AND
An orderBy array that sorts the returned data
A pagination object to request the results to be returned in a paged fashion
- It is recommended that API developers/users/customers use pagination to obtain results. A combination of pageNumber, pageSize and totalCount can be used to page through results in an efficient manner.

Limitations

Fields cannot include specific extensions/custom fields, just the general field “extensions”

Search Criteria

A search combines a property, an operator, and a value. Since the search is an array, elements can be combined using the condition property with a value of 'and'.

Search Property	Definition

Search Property	Definition
name	"name": "accountID" Type: String The property you want to base the search on. For a list of elgible filter properties you can review the API documentation.
operator	"operator": "eq" Type: String The search operator you want to use. Possible values include: eq, notEq, lt, ltEq, gt, gtEq, contains, etc.
value	"value": 42 Type: Number The value or range of values to search the property on. For a list, use comma separated values.
condition	"condition": "and" Type: String The condition property is used to chain together search in the array.

Here is an example of a basic search:

{
    "query": {
      "top": 10,
      "search": [
        {
            "name": "name",
            "value": "Admin",
            "operator": "eq"
        }
      ]
    }
}

Combining Searches

Elements in the search array are combined using the AND condition and by adding a new element to the array. Building on our previous example, here is an example of a search with two conditions:

{
    "query" {
      "top": 10,
      "search": [
          {
              "name": "name",
              "value": "Admin",
              "operator": "eq",
              "condition": "and"
          },
          {
              "name": "currencyId",
              "operator": "eq",
              "value": 1
          }
      ]
    }
}

Ordering Searches

The orderBy property allows you to sort the response items by ascending or descending values based on one of the properties. Let's add an orderby condition to our example:

{
    "query": {
      "top": 10,
      "search": [
          {
              "name": "name",
              "value": "Admin",
              "operator": "eq",
              "condition": "and"
          },
          {
              "name": "currencyId",
              "operator": "gt",
              "value": 1
          }
      ],
      "condition": "and",
      "orderBy": [
          {
              "name": "created",
              "direction": "desc"
          }
      ]
    }
}

Pagination in Searches

To ensure that the data returned isn’t excessive data one should use the pagination object. This ensures that the results are returned in a way that the pages of data can be controlled.

Making the Request

Let's send the JSON payload down on a POST request. The resulting JavaScript XHR code snippet:

The Results

The return data from the request will be in the form of an array. An example of this return data is shown below: