Search Requests

Last verified with: 10.8.6.0

Search requests let you filter, sort, and paginate resource collections using a POST request to the resource's /Search route.

Use a search request when you need more control than a basic GET, especially when you want to:

• filter on one or more fields
• sort results
• limit result size
• page through large result sets

Route Pattern

Use the /Search route for the resource you want to query.

Example:

POST /api/vX/Account/Search
Content-Type: application/json
Authorization: Bearer <token>

Replace vX with the API version you are targeting.

Request Structure

A search request is sent as JSON in the request body.

Basic structure:

{
  "query": {
    "top": 10,
    "search": [
      {
        "name": "name",
        "operator": "eq",
        "value": "Admin"
      }
    ],
    "orderBy": [
      {
        "name": "created",
        "direction": "desc"
      }
    ],
    "pagination": {
      "pageNumber": 1,
      "pageSize": 10
    }
  }
}

Query Properties

top

Limits the number of records returned.

• If omitted, the default is typically 100
• The documented upper bound is 10000
• Use pagination instead of very large top values when working with large datasets

search

An array of filter conditions.

Each search item includes:

• name: the field to filter on
• operator: the comparison operator
• value: the value to compare against

Example:

{
  "name": "currencyId",
  "operator": "eq",
  "value": 1
}

Supported operators include:

• eq:
  Returns records where the field exactly matches the supplied value.
• notEq:
  Returns records where the field does not match the supplied value.
• lt:
  Returns records where the field is less than the supplied value.
• ltEq:
  Returns records where the field is less than or equal to the supplied value.
• gt:
  Returns records where the field is greater than the supplied value.
• gtEq:
  Returns records where the field is greater than or equal to the supplied value.
• isNull:
  Returns records where the field has no value.
• isNotNull:
  Returns records where the field contains a value.
• between:
  Returns records where the field value falls within the supplied start and end range, inclusive.
• notBetween:
  Returns records where the field value falls outside the supplied start and end range.
• startsWith:
  Returns records where the field begins with the supplied text.
• notStartsWith:
  Returns records where the field does not begin with the supplied text.
• endsWith:
  Returns records where the field ends with the supplied text.
• notEndsWith:
  Returns records where the field does not end with the supplied text.
• contains:
  Returns records where the field contains the supplied text anywhere in the value.
• notContains:
  Returns records where the field does not contain the supplied text.
• in:
  Returns records where the field matches any value in the supplied list.
• notIn:
  Returns records where the field does not match any value in the supplied list.

Always confirm the supported fields and operators for the specific resource in that resource's API documentation.

condition

Use condition to control how multiple search clauses are combined.

In practice, this should be understood as joining search filters, not sorting rules.

If your request includes multiple filters, be explicit about how they should combine.

Example:

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

Sorting With orderBy

Use orderBy to sort the returned results.

Example:

"orderBy": [
  {
    "name": "created",
    "direction": "desc"
  }
]

Typical directions are:

• asc
• desc

Pagination

Use pagination when you expect more than a small number of records.

Example:

"pagination": {
  "pageNumber": 1,
  "pageSize": 10
}

Pagination is the preferred approach for production integrations because it keeps responses predictable and easier to process.

Example: Single Filter

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

Example: Multiple Filters With Sorting

{
  "query": {
    "search": [
      {
        "name": "name",
        "operator": "eq",
        "value": "Admin",
        "condition": "and"
      },
      {
        "name": "currencyId",
        "operator": "gt",
        "value": 1
      }
    ],
    "orderBy": [
      {
        "name": "created",
        "direction": "desc"
      }
    ],
    "pagination": {
      "pageNumber": 1,
      "pageSize": 25
    }
  }
}

Example Request

curl -X POST "https://your-domain/api/vX/Account/Search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": {
      "pagination": {
        "pageNumber": 1,
        "pageSize": 10
      },
      "search": [
        {
          "name": "name",
          "operator": "eq",
          "value": "Admin"
        }
      ]
    }
  }'

Response Shape

Search responses return an object that contains metadata plus an items array.

Example:

{
  "trackingId": "d2ae5304-2355-44eb-a328-272f02935f8b",
  "itemCount": 1,
  "items": [
    {
      "id": 2,
      "name": "Admin"
    }
  ]
}

Do not treat the response itself as a raw array. The records are returned inside items.

Implementation Guidance

• Prefer pagination for integrations that may return many records
• Be explicit about sort order when result order matters
• Use only documented field names for the target resource
• Treat search and filter support as resource-specific, especially for related fields and extensions
• Test search payloads against the exact API version your integration uses