Overseer Rules Engine ⚙️
Overview
Overseer is a flexible, dynamic rules engine designed to process, validate, and enforce business rules around insurance card data. Currently production-ready and used internally for card validation and eligibility processing, Overseer is now available to select clients.
By tailoring rules to the specific needs of each account, Overseer ensures accuracy, efficiency, and adaptability for a variety of use cases, particularly in eligibility requests.
Current Availability
Overseer is available as an add-on feature for Enterprise accounts. Contact the CardScan team to discuss pricing, rule creation, testing, and deployment for your specific use cases.
Simple Rule Examples
Here are examples of simple rules that can be defined within Overseer:
Post-Card-Scanning Example
{
"id": "rule_001",
"name": "Block Medicare cards from eligibility workflow",
"trigger": "post_card_scanning",
"conditions": {
"any": [
{ "field": "card.payer_name", "comparison": "contains", "value": "Medicare" },
{ "field": "card.payer_name", "comparison": "contains", "value": "CMS" }
]
},
"actions": [
{
"type": "block_request",
"message": "Medicare eligibility verification not supported via this workflow. Please use dedicated Medicare portal."
}
],
"description": "Block Medicare cards from continuing to eligibility verification."
}Pre-Eligibility Example
{
"id": "rule_002",
"name": "Modify member ID for XYZ Insurance",
"trigger": "pre_eligibility_request",
"conditions": {
"all": [
{ "field": "card.payer_name", "comparison": "equals", "value": "XYZ Insurance" },
{ "field": "card.member_number", "comparison": "startsWith", "value": "128" }
]
},
"actions": [
{
"type": "prepend_value",
"field": "eligibility_request.subscriber.member_id",
"set_value": "000"
}
],
"description": "If payer is XYZ Insurance and member ID starts with '128', prepend '000' to member ID."
}Capabilities
Dynamic Rule Management
Rules are loaded on a per-account basis, allowing for customized processing tailored to client-specific requirements.
Rules can be updated without disrupting existing workflows.
Flexible Rule Evaluation
Supports a wide range of conditions, including validations, checks, and thresholds.
Rules can be simple (e.g., verifying required fields) or more advanced (e.g., cross-checking values with approved lists, calling external APIs).
Clear and Actionable Outcomes
Each rule can modify the underlying payload or provide a clear outcome, such as approve, reject, or flag for further review.
If a rule adjusts the payload, Overseer can optionally re-run affected rules to ensure the changes are fully evaluated.
Rules are evaluated sequentially, ensuring transparency in decision-making.
Scalable Processing
Overseer can handle high volumes of data efficiently, ensuring timely and reliable results for large-scale operations.
Common Use Cases
Overseer is designed to address a variety of scenarios, particularly for pre-eligibility workflows:
Validate Card Data: Ensure extracted card information meets quality standards and required field completeness.
Enrich Card Data: Add missing information or standardize data formats using external APIs or internal databases.
Route Based on Payer: Direct different payers through specific workflows or block unsupported payers.
Validate Member Details Before RTE: Ensure all required member information is accurate and complete before real-time eligibility requests.
Adjust Payload Before RTE Request: Modify or enrich request payload data to align with payer-specific requirements.
Redirect RTE Requests: Dynamically modify the routing of real-time eligibility (RTE) requests based on specific rules, such as payer identification, regional preferences, or account-specific routing logic.
Custom Payer Match: Match card details against a custom-defined lists of approved or prioritized payers.
Match Patients Against Employer or MPI: Cross-reference patient data with employer records or a centralized master patient index (via internal DB or API).
Additional Custom Rules: Support account-specific rules that align with unique business workflows.
Rule Structure & Capabilities
1️⃣ Triggers
Rules can be executed at different points in the card scanning and eligibility request lifecycle, with access to different data contexts:
post_card_scanning
Runs after card scanning is complete. Used for validating, enriching, or routing based on extracted card data.
Card data only
pre_eligibility_request
Runs before eligibility is checked. Used for modifying or validating the request payload.
Card data + Eligibility request object
post_eligibility_request
Runs after eligibility is checked. Used for modifying or analyzing the response.
Card data + Eligibility request + Eligibility response
failed_eligibility_request
Runs when an eligibility request fails due to an error or rejection.
Card data + Eligibility request + Error details
2️⃣ Conditions
Conditions define when a rule is applied. They support AND and OR logic:
all
AND logic – All conditions in this group must be true for the rule to apply.
any
OR logic – At least one condition in this group must be true for the rule to apply.
Operators
equals
Exact match comparison. Example: "card.payer_name" equals "XYZ Insurance"
startsWith
Checks if a string starts with a specific value. Example: "card.member_number" starts with "128"
dateBefore
Checks if a date field is in the past. Example: "eligibility_request.subscriber.date_of_birth" dateBefore "today"
dateAfter
Checks if a date field is in the future. Example: "eligibility_request.subscriber.effective_date" dateAfter "today"
contains
Checks if a value exists within an array or string. Example: "eligibility_response.services" contains "authorized"
greaterThan
Checks if a numerical field is greater than a given value. Example: "eligibility_response.copay" greaterThan 25
lessThan
Checks if a numerical field is less than a given value. Example: "eligibility_response.deductible.remaining" lessThan 500
Available Data Context
The data available to rules depends on the trigger point:
Post-Card-Scanning Context
{
"card": {
"card_id": "uuid",
"member_number": "12345",
"payer_name": "XYZ Insurance",
"member_name": "John Doe",
"group_number": "GRP001",
"plan_name": "Choice Plus",
"rx_bin": "610279",
"rx_pcn": "9987"
}
}Pre-Eligibility Context
{
"card": {
"card_id": "uuid",
"member_number": "12345",
"payer_name": "XYZ Insurance",
"member_name": "John Doe",
"group_number": "GRP001"
},
"eligibility_request": {
"subscriber": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "19900101",
"member_id": "12345"
},
"provider": {
"npi": "1234567890",
"first_name": "Jane",
"last_name": "Smith"
}
}
}Post-Eligibility Context (includes all above plus)
{
"eligibility_response": {
"services": ["authorized"],
"copay": 25.00,
"deductible": {
"remaining": 500.00
},
"coverage": {
"active": true,
"effective_date": "2024-01-01"
}
}
}3️⃣ Actions List
Actions define how a request or response is modified:
modify_request
Modifies a request field.
block_request
Blocks the request and returns a reason.
return_custom_response
Modifies the response and sets a custom message.
prepend_value
Pre-pends a string to a field (e.g., "000" + memberId).
append_value
Appends a string to a field.
replace_value
Replaces a field value with a new value.
log
Logs a message for debugging.
set_flag
Adds a flag to the request or response.
send_webhook
Sends a webhook notification (Coming Soon!)
Additional Parameters
name- A human friendly display name for the rule.id- Unique identifier for the rule.description- A helpful description for understanding a rules purpose and for debugging, not used in processing.
Rule Execution Order & Dependencies
Overseer evaluates rules sequentially, ensuring deterministic processing. If a rule modifies a request or response, any dependent rules will re-evaluate as needed. Rules can be structured to minimize unintended overrides.
Post-Eligibility Rules for Modifying Responses
Post-eligibility rules allow dynamic modifications to eligibility responses before they are finalized. Rules can:
Flag responses with metadata (e.g.,
"pre_approved": trueif services are authorized).Modify the return message based on conditions.
Override or enhance eligibility decisions dynamically.
Example Use Case:
An eligibility check returns "authorized" services.
The rule sets a flag (
pre_approved: true) for downstream processing.The final response message is overwritten to reflect service authorization.
{
"id": "rule_008",
"name": "Modify response for authorized services",
"trigger": "post_eligibility_request",
"conditions": {
"all": [
{ "field": "eligibility_response.services", "comparison": "contains", "value": "authorized" }
]
},
"actions": [
{
"type": "set_flag",
"field": "eligibility_response.metadata.pre_approved",
"value": true
},
{
"type": "return_custom_response",
"message": "Services authorized. Eligibility confirmed."
}
],
"description": "If the eligibility response contains 'authorized' services, mark as pre-approved and update response."
}Webhook-Driven Preprocessing for Eligibility Rules
Our eligibility rules support pre-fetching external data before processing, allowing customers to integrate their own APIs for additional checks. This ensures eligibility decisions can incorporate real-time approvals, employer verification, or other business logic without modifying the request manually.
Before an eligibility request is processed, a customer-configured webhook is called. The webhook response is then injected into the request context, allowing rules to evaluate the additional data just like any other condition.
Key Benefits
✅ Flexible API Integration → Use your own API to check patient pre-approval, employer verification, or other conditions.
✅ Secure Credential Management → API keys are stored in AWS Secrets Manager and injected dynamically.
✅ Seamless Rule Execution → Webhook responses are mapped into conditions without additional processing logic.
✅ Configurable Timeouts & Failover → Define webhook timeouts to ensure smooth operation even if the external API is slow.
Example Use Case
If a patient is already pre-approved, the rule can skip the eligibility request and return a response immediately:
The webhook is called with
{ "memberId": "12345" }.The API returns
{ "patient_approved": true }.A rule detects this and skips the eligibility check, returning
"Patient is already approved, skipping eligibility check.".
Example Webhook Rule
{
"id": "rule_006",
"name": "Skip eligibility check for pre-approved patients",
"trigger": "pre_eligibility_request",
"conditions": {
"all": [
{ "field": "patient_approved", "comparison": "equals", "value": true }
]
},
"actions": [
{
"type": "return_custom_response",
"message": "Patient is already approved, skipping eligibility check."
}
],
"description": "If patient is pre-approved from external API, do not process eligibility.",
"webhooks": {
"pre_eligibility": {
"method": "POST",
"url": "https://customer-api.com/pre-eligibility",
"headers": {
"Authorization": "Bearer {{aws_secrets:customer_api_key}}",
"Content-Type": "application/json"
},
"timeout": 3000,
"body": {
"member_id": "{{card.member_number}}",
"payer_name": "{{card.payer_name}}"
}
}
}
}Placeholders in webhook configurations (e.g., {{request.memberId}}, {{secrets:customer_api_key}}) are dynamically resolved when the rule executes. Request-related placeholders map to the incoming payload, while secret placeholders securely fetch stored values.
Error Handling
If a rule encounters an error during evaluation, Overseer logs the failure and proceeds based on the rule configuration. Webhook calls that fail due to timeouts or HTTP errors can be retried (if configured). Rules can also define fallback behavior for such cases.
Common Error Scenarios
Field not found: Rule is skipped and logged as a warning. The request continues processing with remaining rules.
Webhook timeout: Rule continues with default behavior. If configured, webhook calls can be retried up to 3 times.
Invalid comparison: Rule fails validation and is skipped. The error is logged and the request continues.
Action failure: Rule logs the error but the request continues processing. Partial modifications may be applied.
Rule syntax error: Rule is disabled until corrected. All other rules continue to function normally.
Important: Rule failures are non-blocking. If a rule encounters an error, the eligibility request will continue processing to ensure system reliability.
Logging & Debugging (coming soon)
Overseer provides detailed logs for each rule execution, including:
Which rules were evaluated.
Which conditions passed/failed.
How request/response data was modified.
Clients can enable debug mode for additional visibility when testing new rule configurations.
Performance & Limits
Overseer is designed for high-throughput processing with the following performance characteristics and limits:
Execution Limits
Rule execution timeout: 5 seconds per rule
Maximum rules per account: 100 active rules
Maximum conditions per rule: 25 conditions
Webhook timeout: 3 seconds (configurable up to 10 seconds)
Maximum webhook retries: 3 attempts
Performance Metrics
Rule evaluation: Typically < 50ms per rule
Webhook calls: Add 100-3000ms depending on external API response time
Throughput: Supports 1000+ eligibility requests per minute
Latency impact: Rules add ~100-500ms to eligibility request processing time
Optimization Tips
Keep conditions simple: Complex nested conditions take longer to evaluate
Minimize webhook calls: Use webhooks only when external data is essential
Order rules strategically: Place frequently-triggered rules first for faster evaluation
Use specific triggers: Avoid rules that run on every request when possible
Last updated
Was this helpful?