> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Risk models and scoring

> Understand Straddle's identity and fraud risk assessment system, including decision logic, risk scores, correlation scores, and how scores affect approvals.

Straddle's identity verification engine uses machine learning models trained on millions of data points to assess risk in real-time. When you create a customer, multiple scoring models analyze different aspects of the provided information—from synthetic identity patterns to email reputation—delivering a comprehensive risk assessment within milliseconds.

## What This Guide Covers

* **Decision outcomes**: How Straddle determines customer status (verified, review, rejected)
* **Risk scores**: Understanding fraud and synthetic identity scoring ranges
* **Correlation scores**: How PII elements are validated against each other
* **Breakdown structure**: Accessing detailed scores for each verification module
* **Implementation patterns**: Using scores to optimize approval rates

## Understanding the Review Response

When you call `GET /v1/customers/{id}/review`, the response contains detailed scoring breakdowns organized by verification module:

```json theme={null}
{
  "identity_details": {
    "breakdown": {
      "fraud": {
        "decision": "accept",
        "risk_score": 0.125,
        "codes": ["I520", "I601"]
      },
      "synthetic": {
        "decision": "accept", 
        "risk_score": 0.089,
        "codes": ["I1004"]
      },
      "email": {
        "decision": "accept",
        "correlation_score": 0.75,
        "correlation": "match",
        "codes": ["I556"]
      },
      "phone": {
        "decision": "accept",
        "correlation_score": 0.82,
        "correlation": "match",
        "codes": ["I618"]
      },
      "address": {
        "decision": "accept",
        "correlation_score": 0.91,
        "correlation": "match",
        "codes": ["I708"]
      }
    }
  }
}
```

### Breakdown Modules

Each module evaluates a specific aspect of identity:

| Module                    | Purpose                                                  | Key Metrics                        |
| ------------------------- | -------------------------------------------------------- | ---------------------------------- |
| `fraud`                   | Overall fraud risk assessment                            | `risk_score`                       |
| `synthetic`               | Synthetic identity detection                             | `risk_score`                       |
| `email`                   | Email reputation and correlation                         | `correlation_score`, `correlation` |
| `phone`                   | Phone verification and correlation                       | `correlation_score`, `correlation` |
| `address`                 | Address validation and correlation                       | `correlation_score`, `correlation` |
| `business_identification` | Business-specific verification (business customers only) | Various                            |

### Decision Values

Each module returns a `decision` field with one of these values:

| Decision | Meaning                    | Impact on Customer Status        |
| -------- | -------------------------- | -------------------------------- |
| `accept` | Module passed verification | Contributes to `verified` status |
| `review` | Manual review recommended  | May trigger `review` status      |
| `reject` | Module failed verification | May trigger `rejected` status    |

<Note>
  The overall customer status is determined by combining all module decisions. A single `reject` or multiple `review` decisions typically result in a non-verified status.
</Note>

## Risk Scores

Risk scores predict the likelihood of fraud, with higher scores indicating greater risk:

### Score Interpretation

Risk scores range from 0 to 1, with higher scores indicating greater risk. Your platform should define thresholds based on your risk tolerance.

### Fraud Risk Score

The `fraud.risk_score` evaluates overall identity fraud probability based on:

* Consistency of provided PII
* Velocity patterns (multiple applications)
* Known fraud indicators
* Behavioral anomalies

### Synthetic Identity Risk Score

The `synthetic.risk_score` specifically detects fabricated identities:

* Randomized SSN patterns
* Inconsistent credit history
* Unusual PII combinations
* Missing digital footprint

### Accessing Risk Scores

```javascript theme={null}
// Get detailed review information
const review = await straddle.customers.review(customerId);

// Access risk scores from breakdown
const fraudScore = review.identity_details.breakdown.fraud.risk_score;
const syntheticScore = review.identity_details.breakdown.synthetic.risk_score;

if (fraudScore > 0.7 || syntheticScore > 0.9) {
  // High risk - implement additional verification
  console.log('Customer requires enhanced due diligence');
}
```

## Correlation Scores

Correlation scores measure how well PII elements match authoritative data sources:

### Correlation Categories

The `correlation` field categorizes the strength of correlation:

| Category          | Meaning                                               |
| ----------------- | ----------------------------------------------------- |
| `high_confidence` | Strong correlation - PII elements verified together   |
| `likely_match`    | Good correlation - most elements match                |
| `potential_match` | Partial correlation - some elements match             |
| `low_confidence`  | Weak or no correlation - elements don't match records |

### Module-Specific Correlations

* **Email Correlation**: Verifies email ownership and age
* **Phone Correlation**: Confirms phone number association
* **Address Correlation**: Validates current residence

### Using Correlation Scores

```javascript theme={null}
const review = await straddle.customers.review(customerId);
const { email, phone, address } = review.identity_details.breakdown;

// Check correlation strength
if (email.correlation === 'low_confidence') {
  console.log('Email cannot be verified - request alternative email');
}

if (phone.correlation_score < 0.5) {
  console.log('Weak phone correlation - verify phone ownership');
}

// All correlations strong
if (email.correlation === 'high_confidence' && 
    phone.correlation === 'high_confidence' && 
    address.correlation === 'high_confidence') {
  console.log('All PII elements strongly correlated');
}
```

## KYC Validation

The `kyc` object in the review response provides field-level validation:

```json theme={null}
{
  "identity_details": {
    "kyc": {
      "decision": "accept",
      "codes": ["I998"],
      "validations": {
        "first_name": true,
        "last_name": true,
        "address": true,
        "city": true,
        "state": true,
        "zip": true,
        "phone": true,
        "email": true,
        "dob": true,
        "ssn": false  // SSN doesn't match records
      }
    }
  }
}
```

### Field Validation Results

* `true`: Field matches authoritative data sources
* `false`: Field doesn't match or cannot be verified
* Field may be omitted if not provided

### Using KYC Results

```javascript theme={null}
const review = await straddle.customers.review(customerId);
const kyc = review.identity_details.kyc;

// Check overall KYC decision
if (kyc.decision !== 'accept') {
  console.log('KYC verification failed');
}

// Count failed validations
const failedFields = Object.entries(kyc.validations)
  .filter(([field, valid]) => valid === false)
  .map(([field]) => field);

if (failedFields.length > 0) {
  console.log(`Failed KYC fields: ${failedFields.join(', ')}`);
  // Request correction of specific fields
}
```

## Implementation Best Practices

<CardGroup cols={2}>
  <Card title="Manual Customer Review" icon="sliders">
    * Design a workflow to handle customers needing review
    * Identify common review scenarios for your organization
    * Provide operations users with guidance on how to handle specific cases
  </Card>

  <Card title="Monitor Patterns" icon="chart-line">
    * Track average risk scores over time
    * Identify common reason codes
    * Analyze correlation patterns
    * Optimize data collection
  </Card>

  <Card title="Handle Edge Cases" icon="code-branch">
    * Implement fallbacks for `unknown` correlations
    * Collect additional data when needed
    * Provide clear user feedback
    * Document decision rationale
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    * Use sandbox to test score ranges
    * Simulate different risk scenarios
    * Verify decision logic
    * Monitor false positive rates
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Reason Codes" icon="list" href="/guides/identity/reasons">
    Understand the specific codes returned with scores
  </Card>

  <Card title="Customer Review" icon="eye" href="/api-reference/customers/review">
    API reference for accessing detailed scores
  </Card>

  <Card title="Watchlists" icon="shield" href="/guides/identity/watchlists">
    Learn about sanctions and PEP screening
  </Card>

  <Card title="Business Identity" icon="building" href="/guides/identity/business_identity">
    Special scoring for business customers
  </Card>
</CardGroup>