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.
Fields cannot include specific extensions/custom fields, just the general field “extensions”
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'.
Here is an example of a basic search:
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:
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:
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
The return data from the request will be in the form of an array. An example of this return data is shown below: