Search Requests

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 formula 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
name	The property you want to base the search on. For a list of elgible filter properties you can review the API documentation.
operator	The search operator you want to use. Possible values include: eq, notEq, lt, ltEq, gt, gtEq, contains, etc.
value	The value or range of values to search the property on. For a list, use comma separated values
condition	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.

{
    "query": {
      "pagination": {
            "pageNumber": 1,
            "pageSize": 10
      },
      "search": [
          {
              "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:

xhr.open("POST", "https://mydomain.com/ResourceServer/api/v10/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\": \"Admin\",\"operator\": \"eq\"}]}}");

The Results:

{
    "trackingId": "d2ae5304-2355-44eb-a328-272f02935f8b",
    "itemCount": 1,
    "items": [
        {
            "identity": 1,
            "currencyId": 8,
            "currencyCode": "USD",
            "currencyName": "Sample Text Data",
            "ownerId": 16,
            "ownerName": "Sample Text Data",
            "name": "Admin",
            "created": "2021-04-26T15:25:27.587Z",
            "accountStatusTypeId": 25,
            "accountStatusTypeName": "Sample Text Data",
            "billGroupId": 27,
            "billGroupName": "Sample Text Data",
            "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": 3,
            "invoicerAccountName": "Sample Text Data",
            "usageInvoicerAccountId": 2,
            "usageInvoicerAccountName": "Sample Text Data",
            "taxSettingAccountId": 1,
            "taxSettingAccountName": "Sample Text Data",
            "usageBillDay": 1,
            "isReadOnlyBillDay": true,
            "isReadOnlyUsageBillDay": false,
            "displayName": "Sample Text Data",
            "createdByUserId": 17,
            "createdByUserName": "Sample Text Data",
            "id": 2
        }
    ]
}