# Enriched Results 🔍

CardScan's AI-powered enrichment extracts additional structured data from insurance cards beyond the standard OCR processing. This includes labeled phone numbers, addresses, and copayment information with high confidence scores ready to be used in your business processes.

## Overview

The enriched results feature uses advanced AI models to perform sophisticated extraction from insurance card images. This is a secondary process that runs after the standard card scanning is completed, providing additional data points with enhanced accuracy.

**Important:** Enriched results processing uses a secondary model processing pipeline with about 8 seconds of latency after standard card processing completes. Your application should handle both the initial `completed` state and the subsequent `enriched` state with enhanced data.

## Use Cases

**Automated Benefits Verification:** Extract high-reliability `provider_services_phone` numbers from insurance cards to use with manual or AI-automated voice benefits checking systems, eliminating the need to manually search for correct provider contact numbers.

**Claims Processing Automation:** Automatically route claims to the correct mailing addresses by extracting labeled `medical_claims_address` and `pharmacy_claims_address` information, reducing processing delays and improving accuracy in claims submission workflows.

**Payer Deduplication:** De-duplicate payers using extracted claims addresses and member services phone numbers to identify when different insurance plans belong to the same parent organization, improving data quality and reducing redundant payer records in your system.

## Accessing Enriched Results

### API Response Structure

When a card reaches the `enriched` state, the enriched data is available in the `enriched_results` field:

```json
{
  "card_id": "01234567-89ab-cdef-0123-456789abcdef",
  "state": "enriched",
  "enriched_results": {
    "addresses": [
      {
        "label": "Send Claims to",
        "type": "medical_claims_address",
        "company_name": "ABC Health Plans",
        "address": "PO Box 9999, Phoenix, AZ 85001",
        "score": "0.990"
      }
    ],
    "phone_numbers": [
      {
        "label": "Member Services",
        "type": "member_services_phone",
        "number": "555-123-4567",
        "score": "0.980"
      }
    ],
    "copays_deductibles": [
      {
        "service": "office_visit",
        "category": "copay",
        "value": 40,
        "score": "0.950"
      }
    ],
    "processed_sides": "both"
  }
}
```

### Field Descriptions

#### Address Fields

* `label`: Descriptive text found on the card (e.g., "Send Claims to", "Mail Appeals to")
* `type`: Standardized address category
* `company_name`: Organization or company name associated with the address
* `address`: The actual mailing address
* `score`: Confidence score as a string with 3 decimal places (0.000-1.000)

#### Phone Number Fields

* `label`: Descriptive text found on the card (e.g., "Member Services", "For prior-auth call")
* `type`: Standardized phone number category
* `number`: Phone number in NPA-NXX-XXXX format (e.g., "415-555-1212")
* `score`: Confidence score as a string with 3 decimal places (0.000-1.000)

#### Copay/Deductible Fields

* `service`: Type of medical service
* `category`: Cost type (copay, coinsurance, deductible, out\_of\_pocket\_max)
* `value`: Numeric amount
* `score`: Confidence score as a string with 3 decimal places (0.000-1.000)

#### Processing Indicator

* `processed_sides`: Indicates whether AI processing analyzed "front\_only" or "both" sides of the card

## Address Types

| Type                      | Description                              |
| ------------------------- | ---------------------------------------- |
| `medical_claims_address`  | Address for submitting medical claims    |
| `pharmacy_claims_address` | Address for pharmacy/prescription claims |
| `vision_claims_address`   | Address for vision benefit claims        |
| `dental_claims_address`   | Address for dental benefit claims        |
| `appeals_address`         | Address for appeals and grievances       |
| `pcp_address`             | Primary care provider office address     |
| `general_address`         | General contact or corporate address     |

## Phone Number Types

| Type                      | Description                        |
| ------------------------- | ---------------------------------- |
| `pcp_phone`               | Primary care provider phone number |
| `member_services_phone`   | Member/customer service line       |
| `provider_services_phone` | Provider services phone number     |
| `pharmacy_services_phone` | Pharmacy benefit phone number      |
| `dental_benefit_phone`    | Dental benefits phone number       |
| `vision_benefit_phone`    | Vision benefits phone number       |
| `telemedicine_phone`      | Telemedicine services phone number |

## Copay Services

| Service                  | Description                     |
| ------------------------ | ------------------------------- |
| `office_visit`           | Primary care office visits      |
| `specialist_visit`       | Specialist consultations        |
| `emergency_room`         | Emergency room visits           |
| `urgent_care`            | Urgent care visits              |
| `preventive_care`        | Preventive care services        |
| `prescription`           | Prescription medications        |
| `vision`                 | Vision care services            |
| `dental`                 | Dental care services            |
| `telemedicine`           | Telemedicine consultations      |
| `in_network_medical`     | In-network medical services     |
| `out_of_network_medical` | Out-of-network medical services |
| `other`                  | Other medical services          |

## Copay Categories

| Category            | Description                     |
| ------------------- | ------------------------------- |
| `copay`             | Fixed dollar amount copayment   |
| `coinsurance`       | Percentage-based cost sharing   |
| `deductible`        | Annual deductible amount        |
| `out_of_pocket_max` | Annual out-of-pocket maximum    |
| `other`             | Other cost-sharing arrangements |

## Card States and Processing

### Sequential Processing Flow

CardScan uses a two-stage processing pipeline:

1. **Primary Processing**:
   * `pending` → Card created, awaiting processing
   * `processing` → OCR and ML processing in progress
   * `completed` → Standard processing finished, basic card data available
2. **Secondary Processing** (approximately 8 seconds additional):
   * `enriched` → AI enrichment completed, enhanced data available (final state)

### Processing Timeline

* **Standard card details** (member numbers, payer info, etc.) are available when state reaches `completed`
* **Enriched results** (labeled phone numbers, addresses, copays) are available when state reaches `enriched`
* **Background processing**: Enrichment runs automatically after completion without blocking the primary workflow

## Feature Availability

### Feature Flag

Enriched results require the `post_processing_enriched_results` feature flag to be enabled for your account. Contact support to enable this feature for free.

## Getting Notified of Enrichment Completion

Once a card has finished enrichment processing, you can be notified through several methods:

### Webhook Events

When enrichment completes, a `card.enriched` webhook event is triggered. See the [Webhooks documentation](https://docs.cardscan.ai/advanced-features/webhooks) for setup details.

```json
{
  "type": "card.enriched",
  "card_id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2024-01-15T10:30:00Z",
  "enriched_results": {
    "addresses": [...],
    "phone_numbers": [...],
    "copays_deductibles": [...]
  }
}
```

### WebSocket Updates

Use the client APIs to listen for real-time WebSocket changes when the card state transitions to `enriched`.

### Polling

Poll the card endpoint periodically to check when the state changes from `completed` to `enriched`.

## Best Practices

### Confidence Scores

* Scores above 0.900 are typically very reliable
* Scores between 0.700-0.900 should be validated
* Scores below 0.700 may require manual verification
* All scores are returned as strings with 3 decimal places (e.g., "0.950", "0.123")

### Error Handling

```javascript
// Always check if enriched_results exists
if (card.enrichedResults) {
  // Process enriched data
  const phoneNumbers = card.enrichedResults.phoneNumbers || [];
  const addresses = card.enrichedResults.addresses || [];
  const copays = card.enrichedResults.copaysDeductibles || [];
}
```

## Troubleshooting

### Common Issues

**Enriched results not appearing:**

* Verify the `post_processing_enriched_results` feature flag is enabled
* Check that the card state has reached `enriched`
* Some cards may not have enrichable data (empty arrays are normal)

**Missing data:**

* Not all cards contain phone numbers, addresses, or copay information
* Empty arrays in `enriched_results` indicate no extractable data was found
* Low confidence scores may indicate unclear or damaged card images

**Processing delays:**

* Enrichment requires additional AI processing time
* Complex cards with multiple sides take longer to process
* Network latency can affect processing times

For additional support with enriched results, contact our developer support team.