Search API Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

The VBAPI search functionality is structured around three key components:

1. SearchConfig – Defines the data sources (tables and columns) available for querying.
2. SearchCriteria – Specifies filtering conditions, akin to a SQL WHERE clause.
3. SearchRequest – Combines the search configuration and criteria to execute queries and retrieve results.

Use the navigation links below to explore each part of the search process:

• SearchRequest – Combines config and criteria to retrieve search results.
  • SearchConfig – Defines what data sources (tables/columns) are available.
  • SearchCriteria – Specifies filtering conditions.
• Search Results – Displays the results of the search query.
  • Sorting – Sorting approach for search results.
  • Pagination – Navigate search results across multiple pages.

SearchConfig

A SearchConfig is a predefined set of related tables and columns that serve as the basis for a search. Each SearchConfig represents a logical grouping of data sources.

For example, the CLAIMBATCH SearchConfig includes the following tables:

• CLAIMBATCH
• CLAIMBATCHDETAIL
• CLAIMBATCHES
• PROVIDER
• MEMBERBENEFICIARY
• MEMBERS
• PROCEDURECODE

Using this SearchConfig allows filtering and returning data from any of the above tables.

SearchCriteria

A SearchCriteria object defines the filtering logic for API search operations. It determines which records to include or exclude from your result set, functioning similarly to a WHERE clause in SQL.

Structure of a SearchCriteria Object

Filter Condition Properties

Each object in the criteriaDetails array defines a single filter condition:

Example

The following UI representation illustrates how SearchCriteria are structured:

In the example above:

• The search filters records where Procedure_Code is 99212 and Birth_Date is after 01/01/1974.
• The conditions are combined using the AND operator.

Grouping Conditions

Parentheses can be used to create logical groupings of conditions, similar to SQL expressions. The UI below demonstrates grouped filters:

In this example:

• The first two conditions (Procedure_Code = 99212 AND Birth_Date > 01/01/1974) are enclosed in parentheses.
• The grouped conditions are evaluated together and combined with an OR condition linking another set of filters (Procedure_Code = 1234 AND Birth_Date < 01/01/2020).

JSON Representation of Criteria

Here's how a simple filter (matching Procedure_Code = 99212) is represented in JSON:

{
    "searchConfigId": "CLAIMBATCH",
    "criteria_Key": 84,
    "description": "Claim Batches with Proc Code 99212",
    "criteriaDetails": [
        {
            "criteria_Key": 84,
            "criteria_Seq": 1,
            "criteria_Table": "CLAIMBATCHDETAIL",
            "criteria_Column": "Procedure_Code",
            "criteria_Data_Type": "string",
            "criteria_Operator": "=",
            "criteria_From_Value": "99212",
            "criteria_AndOr": null
        }
    ],
    "temporary": false
}

Multiple Conditions Example

{
  "searchConfigId": "CLAIM",
  "criteria_Key": 92,
  "description": "High Value Claims from Last Month",
  "temporary": true,
  "criteriaDetails": [
    {
      "criteria_Table": "CLAIM",
      "criteria_Column": "Claim_Amount",
      "criteria_Data_Type": "number",
      "criteria_Operator": ">",
      "criteria_From_Value": "5000",
      "criteria_Join": "AND"
    },
    {
      "criteria_Table": "CLAIM",
      "criteria_Column": "Claim_Date",
      "criteria_Data_Type": "date",
      "criteria_Operator": "BETWEEN",
      "criteria_From_Value": "2023-01-01",
      "criteria_To_Value": "2023-01-31"
    }
  ]
}

SearchRequest

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.

SearchRequest Object Reference

Example Request

This request fetches selected fields (First_Name, Last_Name, Procedure_Code) for records matching the defined criteria:

{
    "criteria_Key": 84,
    "searchConfigId": "CLAIMBATCH",
    "selectedFields": [
        { "tableName": "Members", "columnName": "First_Name" },
        { "tableName": "Members", "columnName": "Last_Name" },
        { "tableName": "ProcedureCode", "columnName": "Procedure_Code" }
    ]
}

Advanced Usage Examples

Random Sampling

To get a random subset of the results:

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

Percentage Sampling

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

Nth Result

Return every 5th result from the query:

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

Sorting

By default, results are sorted in ascending order based on the first field in the selectedFields array.

Example Sorting Request

{
    "criteria_Key": 84,
    "searchConfigId": "CLAIMBATCH",
    "selectedFields": [
        { "tableName": "Members", "columnName": "First_Name" },
        { "tableName": "Members", "columnName": "Last_Name" },
        { "tableName": "ProcedureCode", "columnName": "Procedure_Code" }
    ]
}

Here, the results are sorted by First_Name (ascending) as it appears first.

SearchResults

The response includes:

• The SQL query executed (search_SQL_Statement)
• Column mappings (fieldMapping)
• The result set (results)

Example Response

{
    "searchConfigId": "CLAIMBATCH",
    "criteria_Key": 84,
    "search_SQL_Statement": "SELECT * FROM ...",
    "fieldMapping": [
        { "tableName": "Members", "columnName": "First_Name", "columnIndex": 0 },
        { "tableName": "Members", "columnName": "Last_Name", "columnIndex": 1 },
        { "tableName": "ProcedureCode", "columnName": "Procedure_Code", "columnIndex": 2 }
    ],
    "results": [
        ["Jane", "Doe", "99212"],
        ["John", "Smith", "1234"]
    ]
}

Pagination

For large datasets, results are paginated. Include page and pageCount parameters in your request to control pagination.

Example Paginated Request

{
    "criteria_Key": 84,
    "searchConfigId": "CLAIMBATCH",
    "selectedFields": [
        { "tableName": "Members", "columnName": "First_Name" },
        { "tableName": "Members", "columnName": "Last_Name" }
    ],
    "page": 0,
    "pageCount": 100
}

Pagination Response Headers

The X-Pagination response header contains:

{
    "TotalCount": 1000,
    "TotalPages": 10,
    "CurrentPage": 0,
    "PageSize": 100
}

This ensures structured navigation of search results.

Implementation Best Practices

Transient vs. Persistent Criteria

For One-Time Searches (temporary: true)

• Criteria are stored transiently in the system
• Each SearchConfig maintains the five most recent temporary criteria for quick reuse
• Ideal for criteria you may need again in the short term but don't need permanently

For Long-Term Use (temporary: false)

• Criteria are persisted indefinitely in the database
• Recommended for:
  • Frequently used search patterns
  • User-defined filters
  • Report templates
  • Common query definitions

Performance Optimization

• Minimize conditions: Include only necessary filter conditions
• Leverage indexed columns: Prioritize filtering on indexed fields when possible
• Break down complex queries: For intricate search needs, consider multiple smaller, targeted criteria
• Order conditions efficiently: Place the most restrictive conditions first when filtering large datasets