Search Requests

A SearchRequest combines:

A SearchConfig → Defines the tables and columns that are searchable.
A SearchCriteria → Specifies the filtering logic (like a WHERE clause).
A list of selectedFields → Specifies exactly which fields to return in the result set.

This structure allows clients to dynamically query complex, joined datasets while staying within the bounds of predefined configurations.

When to Use a SearchRequest

Use a SearchRequest when:

You want to retrieve specific fields from a known set of related tables.
You need to apply user-driven filtering logic (via SearchCriteria ).
You want clean, paginated data output — especially in UI grids or reports.

SearchRequest Object Reference

Field	Type	Required	Description
`criteria_Key`	integer	✅	The unique ID of the SearchCriteria to apply (like a saved filter).
`searchConfigId`	string	✅	The ID of the SearchConfig to use. Determines table joins and access.
`user_ID`	string or null	❌	The ID of the user performing the seaarch.
`page`	integer or null	❌	If paginating results, specify the page number here (0-indexed).
`pageCount`	integer or null	❌	Number of records per page. Defaults apply if omitted.
`include_Result_Details`	boolean or null	❌	If true, includes extra metadata about the search results.
`use_Random_Sample`	boolean or null	❌	Enables random sampling. Requires `random_Sample_Count`.
`random_Sample_Count`	integer or null	❌	Number of records to randomly sample. Must be 0–1000 (or up to 750 if paging).
`random_Sample_Count_Is_Percent`	boolean or null	❌	If true, `random_Sample_Count` is treated as a percent (0–100).
`use_Nth_Result`	boolean or null	❌	Enables returning every nth result from the dataset when set to `true`.
`nth_Result`	integer or null	❌	Specifies the interval (n) for returning results. Must be ≥ 1.

Advanced Usage Scenarios

Random Sampling

To get a random subset of the results, set use_Random_Sample to true and pass a value in random_Sample_Count.

Copy

Copied

{
  "criteria_Key": 84,
  "searchConfigId": "CLAIMBATCH",
  "use_Random_Sample": true,
  "random_Sample_Count": 100
}

Optional: Set random_Sample_Count_Is_Percent to true if you're specifying a percentage instead of a raw count.

Percent sampling must be between 0–100.

Copy

Copied

{
  "random_Sample_Count": 10,
  "random_Sample_Count_Is_Percent": true
}

Nth Result

If you're interested in returning every nth item from the result set (e.g., "give me every 5th result from this query"), use the useNthResult and nth_Result flags:

Copy

Copied

{
  "criteria_Key": 84,
  "searchConfigId": "CLAIMBATCH",
  "use_Nth_Result": true,
  "nth_Result": 5
}

Pagination Support

If your UI requires paged data, set the page and pageCount values:

Copy

Copied

{
  "criteria_Key": 84,
  "searchConfigId": "CLAIMBATCH",
  "page": 0,
  "pageCount": 50
}

Full Example

Here's a complete example of a SearchRequest with all possible fields:

Copy

Copied

{
  "criteria_Key": 84,
  "searchConfigId": "CLAIMBATCH",
  "user_ID": "matt@example.com",
  "page": 1,
  "pageCount": 100,
  "include_Result_Details": true,
  "use_Random_Sample": true,
  "random_Sample_Count": 50,
  "random_Sample_Count_Is_Percent": false,
  "use_Nth_Result": false,
  "selectedFields": [
    { "tableName": "Members", "columnName": "First_Name" },
    { "tableName": "Members", "columnName": "Last_Name" },
    { "tableName": "Claims", "columnName": "Claim_ID" }
  ]
}