TAG LINE
TAG LINE
SMALL TITLE

v2/v3 GET Filters

Last Updated: Wed May 12 2021

Beginning with v4 of the API search patterns have been changed to use a POST on a “/Search” path to allow for Unicode characters as well as deep search for child objects. The header GET filters described below continue to work in v4 to retain backwards compatibility.

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://mydomain.com/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();