Risk Based Onboarding

This guide explains how to implement conditional routing in your onboarding workflow. Instead of a linear verification journey, this approach dynamically adjusts friction based on real-time risk signals—routing low-risk users through faster verification while applying additional checks for high-risk applicants.

Overview

Risk-Based Onboarding uses a three-step process:

Passive Signal Collection – Assess email, phone, and device risk invisibly
Decision Gate – Route to standard or step-up flow based on risk score
Verification – Execute the appropriate verification path

Configuration Options

Risk-based routing can be configured at different levels depending on your needs:

Option	Signals Used	Best For
Full Fraud Signals	Email, phone, device, IP	Maximum fraud protection
Email + Phone Only	Email reputation, phone intelligence	Lighter integration, good coverage
Business Logic Only	Entity age, product type, transaction value	Simple routing without fraud checks

Option 1: Full Fraud Signals

Uses all available fraud steps: device intelligence, IP risk, email risk, and phone risk. Provides the strongest fraud detection but requires OneSDK integration for device and IP capture. Fraud steps included:

email_risk – Email domain, age, and reputation
phone_risk – Phone type, carrier, and validity
device_intelligence – Device fingerprint, velocity, and blocklist
ip_risk – Geolocation, VPN/proxy detection

Option 2: Email + Phone Only

A lighter approach that assesses risk using email and phone fraud steps. No device fingerprinting or OneSDK integration required. Fraud steps included:

email_risk – Evaluates email domain, age, and reputation
phone_risk – Evaluates phone type, carrier, and validity

Signals evaluated:

Email domain (disposable, free, corporate)
Email age and deliverability
Phone type (mobile, VoIP, landline)
Phone carrier risk and number validity

Option 3: Business Logic Only

Route based on entity attributes or transaction context without fraud signal checks. Useful when risk is determined by business factors rather than fraud indicators.

{
  "stage": "DECISION_GATE",
  "logic": "IF entity_age < 30_days OR product_type == 'HIGH_VALUE' OR transaction_value > 10000",
  "then": "ENHANCED_VERIFICATION",
  "else": "STANDARD_VERIFICATION"
}

Example routing rules:

New customers (entity age < 30 days) → Enhanced verification
High-value products → Document + biometric
Transaction value > threshold → Step-up required
Returning verified customers → Streamlined flow

Prerequisites

Before implementing risk-based routing, ensure you have:

A workflow configured with conditional logic
For fraud signals: Completed the Fraud Checks Guide setup
For device intelligence: OneSDK integration with session tracking

Step 1: Create Entity

Create an entity profile with the data required for your chosen configuration.

curl -X POST https://api.frankieone.com/v2/individuals \
  -H "api_key: YOUR_API_KEY" \
  -H "X-Frankie-CustomerID: YOUR_CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "individual": {
      "entityType": "INDIVIDUAL",
      "name": {
        "givenName": "JAMES",
        "middleName": "A",
        "familyName": "TESTONE",
        "displayName": "JAMES A TESTONE"
      },
      "dateOfBirth": {
        "year": "1990",
        "month": "05",
        "day": "15"
      },
      "nationality": "AUS",
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "streetNumber": "35",
          "streetName": "CONN",
          "streetType": "STREET",
          "unitNumber": "1",
          "locality": "FERNTREE GULLY",
          "subdivision": "VIC",
          "postalCode": "3156",
          "country": "AUS",
          "unstructuredLongForm": "U 1/35 CONN STREET, FERNTREE GULLY, VIC 3156"
        }
      ],
      "emailAddresses": [
        {
          "type": "WORK",
          "email": "[email protected]",
          "isPreferred": true
        }
      ],
      "phoneNumbers": [
        {
          "country": "AUS",
          "number": "0412345678",
          "isPreferred": true
        }
      ],
      "documents": {
        "IDENTITY": [
          {
            "type": "DRIVERS_LICENSE",
            "country": "AUS",
            "subdivision": "VIC",
            "primaryIdentifier": "123456789",
            "secondaryIdentifier": "P1234567",
            "class": "IDENTITY"
          }
        ]
      },
      "consents": [
        { "type": "GENERAL" },
        { "type": "DOCS" },
        { "type": "CREDITHEADER" }
      ]
    }
  }'

The response includes the entityId required for workflow execution.

Note: For device and IP signals, you must implement OneSDK on the client side. Email and phone checks work independently without it.

Step 2: Execute Risk-Based Workflow

Execute your workflow with risk-based routing enabled. The workflow configuration determines how signals are evaluated and which path is triggered.

curl -X POST https://api.frankieone.com/v2/individuals/{entityId}/serviceprofiles/KYC/workflows/AUS-Risk-CDD-Email-Phone-Device/execute \
  -H "api_key: YOUR_API_KEY" \
  -H "X-Frankie-CustomerID: YOUR_CUSTOMER_ID"

Workflow Configuration

Risk-based workflows include fraud steps (email risk, phone risk, device intelligence) that evaluate signals before routing to the appropriate verification path. Below is a conceptual example of the branching structure:

{
  "workflow_name": "Dynamic_Risk_Based_Onboarding",
  "stages": [
    {
      "stage": "PRE_SCREEN",
      "steps": ["email_risk", "phone_risk", "device_intelligence"]
    },
    {
      "stage": "DECISION_GATE",
      "logic": "IF fraud_score > 30 OR device_risk == 'HIGH'",
      "then": "TRIGGER_STEP_UP",
      "else": "STANDARD_FLOW"
    },
    {
      "stage": "VERIFICATION",
      "branches": {
        "STANDARD_FLOW": ["document_ocr", "database_match"],
        "TRIGGER_STEP_UP": ["document_ocr", "biometric_liveness", "database_match"]
      }
    }
  ]
}

Note: This is a conceptual representation. Workflows are configured by your FrankieOne representative. Contact your representative to set up risk-based routing with the appropriate fraud steps for your use case.

Risk Factors Evaluated

The workflow evaluates multiple risk factors, each contributing to the overall risk score:

Risk Factor	Description	Example Values
`fraud_email`	Email Address Risk	LOW, MEDIUM, HIGH
`fraud_phone_number`	Phone Number Risk	LOW, MEDIUM, HIGH
`fraud_ip_address`	IP Address Risk	LOW, MEDIUM, HIGH
`fraud_count_session`	Session Count Risk	Numeric
`entity_type`	Entity Type	INDIVIDUAL
`entity_age`	Age of Entity (years)	Numeric
`workflow_attempts`	Number of Workflow Attempts	Numeric
`document_type`	ID Document Type	DRIVERS_LICENSE, PASSPORT
`address_country_risk`	Residential Address Country	Country code
`document_country_risk`	Document Issuing Country	Country code

Fraud Indicators

The FRAUD step evaluates specific indicators that can trigger issues:

Indicator	Risk Level	Example Triggers
Risky Email Domain	HIGH	Disposable domains, known fraud domains
Email Age	MEDIUM-HIGH	Recently created email addresses
VoIP Phone	MEDIUM-HIGH	Non-mobile phone numbers
Phone Carrier Risk	MEDIUM	High-risk carriers
IP Location Mismatch	MEDIUM	IP doesn’t match stated address
VPN/Proxy Detected	MEDIUM	Connection anonymisation

Step 3: Interpret Results

The workflow execution response contains the full verification outcome in the workflowResult object.

Key Response Fields

Field	Description
`workflowResult.result`	Overall outcome: `PASS`, `REVIEW`, or `FAIL`
`workflowResult.workflowExecutionState`	Execution state: `COMPLETED`
`workflowResult.riskAssessment.riskLevel`	Risk level: `LOW`, `MEDIUM`, or `HIGH`
`workflowResult.riskAssessment.riskScore`	Numeric risk score
`workflowResult.issues`	Array of flagged issues
`workflowResult.steps`	Which steps passed, failed, or are incomplete

Example Response: High-Risk (Needs Review)

This example shows a high-risk result triggered by a risky email domain:

{
  "workflowResult": {
    "entityId": "155da7b9-cb8a-461a-8e58-787d65276630",
    "result": "REVIEW",
    "status": "REVIEW",
    "workflowExecutionState": "COMPLETED",
    "workflowName": "AUS-Risk-CDD-Email-Phone",
    "workflowExecutionId": "01KGJW7WXA0X5QHFC9M31AEE9Q",
    "issues": [
      {
        "category": "FRAUD",
        "issue": "FRAUD_EMAIL_ADDRESS",
        "severity": "REVIEW"
      },
      {
        "category": "RISK",
        "issue": "RISK_THRESHOLD_HIGH",
        "severity": "REVIEW"
      }
    ],
    "riskAssessment": {
      "riskLevel": "HIGH",
      "riskScore": 61,
      "riskFactors": [
        {
          "factor": "fraud_email",
          "description": "Email Address Risk",
          "value": "HIGH",
          "score": 51
        },
        {
          "factor": "fraud_phone_number",
          "description": "Phone Number Risk",
          "value": "LOW",
          "score": 1
        },
        {
          "factor": "fraud_ip_address",
          "description": "IP Address Risk",
          "value": "LOW",
          "score": 1
        },
        {
          "factor": "entity_age",
          "description": "Age of Entity",
          "value": "76",
          "score": 1
        }
      ]
    },
    "steps": {
      "passed": ["START", "MATCHLIST", "DECISION", "FINISH"],
      "failed": ["KYC", "FRAUD"],
      "incomplete": ["TOGGLE_MONITORING"],
      "order": ["START", "MATCHLIST", "KYC", "FRAUD", "TOGGLE_MONITORING", "DECISION", "FINISH"]
    }
  }
}

Understanding the FRAUD Step Results

The workflowStepResults array contains detailed results for each step. For the FRAUD step:

{
  "stepName": "FRAUD",
  "result": "HIT",
  "summary": {
    "maximumEmailAddressRisk": "HIGH",
    "maximumPhoneNumberRisk": "LOW",
    "maximumIpAddressRisk": "LOW",
    "numberEmailAddressEvaluations": 1,
    "numberPhoneNumberEvaluations": 1
  },
  "processResults": [
    {
      "objectType": "EMAIL_ADDRESS",
      "result": "HIT",
      "supplementaryData": {
        "riskLevel": "HIGH",
        "indicators": [
          {
            "name": "emailLevel",
            "value": "high",
            "rules": [{ "name": "Risky Email Domain", "isActive": true }]
          }
        ]
      }
    },
    {
      "objectType": "PHONE_NUMBER",
      "result": "CLEAR",
      "supplementaryData": {
        "riskLevel": "LOW"
      }
    }
  ]
}

Result Values

Result	Meaning	Recommended Action
`PASS`	All checks passed, risk within threshold	Auto-approve account
`REVIEW`	Flags present or risk threshold exceeded	Manual review required
`FAIL`	Critical failure or verification failed	Decline registration

Issue Categories

Category	Example Issues
`FRAUD`	`FRAUD_EMAIL_ADDRESS`, `FRAUD_PHONE_NUMBER`, `FRAUD_DEVICE`
`RISK`	`RISK_THRESHOLD_HIGH`, `RISK_THRESHOLD_MEDIUM`
`KYC`	`NOT_FOUND`, `PARTIAL_MATCH`

Note: Even when individual fraud checks pass, the overall result may be REVIEW if the combined risk score exceeds your configured threshold. This ensures your compliance team can make the final decision with full context.

For detailed field definitions, see Interpreting Workflow Results.

Configuring Thresholds

Work with your FrankieOne representative to tune risk scoring based on your risk appetite.

Risk Score Thresholds

The overall risk score determines the workflow result:

Risk Level	Score Range	Typical Outcome
LOW	0-20	`PASS`
MEDIUM	21-50	`PASS` or `REVIEW` (configurable)
HIGH	51+	`REVIEW`

Risk Factor Weights

Each risk factor contributes a weighted score. Example weights:

Risk Factor	LOW Score	HIGH Score
`fraud_email`	1	51
`fraud_phone_number`	1	51
`fraud_ip_address`	1	51
`entity_type`	2	2
`entity_age`	1	5
`document_type`	1	3
`address_country_risk`	1	10

Note: Weights are configurable. Contact your FrankieOne representative to adjust scoring for your use case.

Best Practices

Always log the workflowExecutionId for audit trails and troubleshooting. Handle REVIEW outcomes by routing to your compliance team with the full flag context rather than auto-declining. Monitor conversion rates by workflow path. If step-up abandonment is high, review your biometric capture UX or threshold settings. Tune thresholds gradually based on observed fraud rates and false positive feedback.

Troubleshooting

Issue	Likely Cause	Resolution
All users getting `REVIEW` result	Risk score threshold too low	Increase threshold or adjust factor weights
`FRAUD_EMAIL_ADDRESS` false positives	Legitimate domains flagged	Review email risk rules with FrankieOne
`KYC` step showing `NOT_FOUND`	No data source matches	Ensure correct document details provided
High `fraud_email` scores	Risky domain patterns	Check if corporate domains need whitelisting
`RISK_THRESHOLD_HIGH` on valid users	Cumulative scores too high	Review individual factor weights
Missing `fraud_phone_number` result	Phone format issue	Ensure phone includes country code

Next Steps

Review the Fraud Checks Guide for signal collection details
See Interpreting Workflow Results for complete field reference
Contact your FrankieOne representative to configure custom thresholds

KYC

​Overview

​Configuration Options

​Option 1: Full Fraud Signals

​Option 2: Email + Phone Only

​Option 3: Business Logic Only

​Prerequisites

​Step 1: Create Entity

​Step 2: Execute Risk-Based Workflow

​Workflow Configuration

​Risk Factors Evaluated

​Fraud Indicators

​Step 3: Interpret Results

​Key Response Fields

​Example Response: High-Risk (Needs Review)

​Understanding the FRAUD Step Results

​Result Values

​Issue Categories

​Configuring Thresholds

​Risk Score Thresholds

​Risk Factor Weights

​Best Practices

​Troubleshooting

​Next Steps