Search API Guide

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.

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 defines the filtering logic applied to a SearchConfig. It consists of individual conditions (filters), which can be combined using AND or OR operators.

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
}

SearchRequest

A SearchRequest applies SearchCriteria to a SearchConfig and defines which columns should be returned.

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" }
    ]
}

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.

By following this guide, developers can efficiently utilize VBAPI’s search capabilities, leveraging filtering, sorting, and pagination for optimal data retrieval.