Search Requests

Many times you will need to filter and sort your GETs. 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 request header. 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 filter 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

Filters

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

Filter Property	Definition
name	"name": "accountID" Type: String The property you want to base the filter on. For a list of elgible filter properties you can use the associated Metadata API.
operator	"operator": "eq" Type: String The filter 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 filter the property on. For a list, use comma separated values.
condition	"condition": "and" Type: String The condition property is used to chain together filters in the array.

Here is an example of a basic filter:

{
    "filters": [
        {
            "name": "name",
            "value": "Admin",
            "operator": "eq"
        }
    ]
}

Combining Filters

Elements in the filters 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 filter with two conditions:

{
    "filters": [
        {
            "name": "name",
            "value": "Admin",
            "operator": "eq",
            "condition": "and"
        },
        {
            "name": "currencyId",
            "operator": "eq",
            "value": 1
        }
    ]
}

Ordering Filters

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:

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

Let's combine two orderBy elements and see what our filter looks like:

{
    "filters": [
        {
            "name": "name",
            "value": "Admin",
            "operator": "eq",
            "condition": "and"
        },
        {
            "name": "currencyId",
            "operator": "eq",
            "value": 1
        }
    ],
    "condition": "and",
    "orderBy": [
        {
            "name": "name",
            "direction": "asc"
        }
    ]
}

Making the Request

Let's add the header to our GET request. The resulting JavaScript XHR code snippet:

xhr.open("GET", "https://35.169.33.81/ResourceServer/api/v1/Account", true);
xhr.setRequestHeader("Accept", "application/json")
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + yourBase64token);
xhr.setRequestHeader("SearchRequest", " [\"{\"filters\":[{\"name\":\"name\",\"value\":\"Admin\",\"operator\":\"eq\",\"condition\":\"and\"},{\"name\":\"currencyId\",\"operator\":\"eq\",\"value\":1}],\"condition\":\"and\",\"orderBy\":[{\"name\":\"created\",\"direction\":\"desc\"},{\"name\":\"name\",\"direction\":\"asc\"}]}\"],");
xhr.send();