Page Comparison

...

Info
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 GETsdata. 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” 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

Filters

...

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 filter search is an array, elements can be combined using the condition property with a value of 'and'.

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

Here is an example of a basic filtersearch:

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

Combining FiltersSearches

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

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

Ordering FiltersSearches

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:

Code Block

{
    "query": {
    "filters  "top": 10,
      "search": [
          {
              "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:

Code Block
{ } }

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.

Code Block
{ "query": { "pagination": { "pageNumber": 1, "pageSize": 10 }, "filterssearch": [ { "name": "name", "value": "Admin", "operator": "eq" } ] } }

Making the Request

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

Code Block

xhr.open("POST", "https://mydomain.com/ResourceServer/api/v4/Account/Search", true);
xhr.setRequestHeader("Accept", "application/json")
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + yourBase64token);
xhr.send("{\"query\": {\"top\": 10,\"search\": [{\"name\": \"name\",\"value\": "condition\"Admin\",\"operator\": "and"
  \"eq\"}]}}");

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:

Code Block

{
    "trackingId": "d2ae5304-2355-44eb-a328-272f02935f8b",
    "itemCount": }1,
    "items": [
        {
            "nameidentity": 1,
            "currencyId": 8,
            "currencyCode": "USD",
            "operatorcurrencyName": "eqSample Text Data",
            "valueownerId": 16,
1         }   "ownerName": "Sample Text ],Data",
            "conditionname": "andAdmin",
     "orderBy": [       "created": "2021-04-26T15:25:27.587Z",
            {"accountStatusTypeId": 25,
            "nameaccountStatusTypeName": "nameSample Text Data",
            "directionbillGroupId": "asc"
 27,
            "billGroupName": "Sample Text Data",
      }     ] }

Making the Request

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

Code Block

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();"actingOwnerId": 6,
            "actingOwnerName": "Sample Text Data",
            "lastUpdate": "2021-04-26T15:25:27.587Z",
            "effectiveCancel": "2021-04-26T15:25:27.587Z",
            "invoiceDeliveryId": 22,
            "invoiceDeliveryName": "Sample Text Data",
            "accountsReceivableTermsId": 24,
            "accountsReceivableTermsName": "Sample Text Data",
            "accountTypeId": 27,
            "accountTypeName": "Sample Text Data",
            "billDay": 1,
            "accountTaxCategoryId": 13,
            "accountTaxCategoryName": "Sample Text Data",
            "taxCodeId": 5,
            "taxCodeName": "Sample Text Data",
            "invoicerAccountId": "My Invoicer Account",
            "invoicerAccountName": "Sample Text Data",
            "usageInvoicerAccountId": "My Usage Invoicer Account",
            "usageInvoicerAccountName": "Sample Text Data",
            "taxSettingAccountId": "My Usage Invoicer Account",
            "taxSettingAccountName": "Sample Text Data",
            "usageBillDay": 1,
            "isReadOnlyBillDay": true,
            "isReadOnlyUsageBillDay": false,
            "displayName": "Sample Text Data",
            "createdByUserId": 17,
            "createdByUserName": "Sample Text Data",
            "id": 2
        }
    ]
}

Versions Compared

Old Version 1

New Version Current

Key