Verification Workflows (Verification Levels)

Verification Workflows define the steps required to verify an applicant's identity. Different workflows can be configured for different use cases, risk levels, or regulatory requirements.

What Are Workflows?

A Workflow (also known as a Verification Level) is a configurable sequence of verification steps that an applicant must complete. Each workflow defines:

Required Steps: Which verification checks must be performed
Step Order: The sequence in which steps are presented
Pass/Fail Criteria: Thresholds for each verification step
Routing Rules: How results map to approval decisions

[Screenshot: Workflow configuration page showing step sequence and settings]

How Workflows Work

Workflow Assignment

When an applicant is created, they are assigned a workflow:

# Create applicant with specific workflow
curl -X POST https://api.bytrustgate.com/api/v1/applicants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "external_id": "user_123",
    "first_name": "John",
    "last_name": "Doe",
    "workflow_id": "wf_standard_kyc"
  }'

Step Execution

Each workflow step transitions through states as verification progresses:

pending → in_progress → complete/failed/skipped

The applicant's overall status reflects the aggregate state of all workflow steps.

Completion Flow

graph LR
    A[Applicant Created] --> B[Steps Initialized]
    B --> C[Step 1: Document]
    C --> D[Step 2: Selfie]
    D --> E[Step 3: Liveness]
    E --> F[Step 4: Screening]
    F --> G[Risk Assessment]
    G --> H{Workflow Rules}
    H -->|Low Risk| I[Auto-Approve]
    H -->|Medium Risk| J[Manual Review]
    H -->|High Risk| K[Escalate/Reject]

Default Workflows

TrustGate provides three pre-configured workflows that cover common verification scenarios.

Standard Workflow

The Standard workflow provides comprehensive identity verification suitable for most regulated use cases.

Step	Type	Description	Required
1	`document`	Government-issued ID upload	Yes
2	`selfie`	Live photo capture	Yes
3	`liveness`	Anti-spoofing check	Yes
4	`screening`	Watchlist screening	Yes

Use Cases:

Financial account opening
Insurance onboarding
Cryptocurrency exchange registration

API Configuration:

{
  "workflow_id": "wf_standard",
  "steps": [
    {"id": "document", "type": "document", "required": true},
    {"id": "selfie", "type": "selfie", "required": true},
    {"id": "liveness", "type": "liveness", "required": true},
    {"id": "screening", "type": "screening", "required": true}
  ]
}

Enhanced Workflow

The Enhanced workflow adds additional verification layers for high-value or high-risk scenarios.

Step	Type	Description	Required
1	`document`	Primary ID (passport/license)	Yes
2	`document_back`	Back of ID (if applicable)	Conditional
3	`selfie`	Live photo capture	Yes
4	`liveness`	Advanced anti-spoofing	Yes
5	`address`	Proof of address document	Yes
6	`screening`	Enhanced watchlist screening	Yes

Use Cases:

High-value account tiers
Business account verification
Regulated financial services
Cross-border transactions

API Configuration:

{
  "workflow_id": "wf_enhanced",
  "steps": [
    {"id": "document_front", "type": "document", "required": true},
    {"id": "document_back", "type": "document", "required": false, "condition": "document_has_back"},
    {"id": "selfie", "type": "selfie", "required": true},
    {"id": "liveness", "type": "liveness", "required": true},
    {"id": "address", "type": "address", "required": true},
    {"id": "screening", "type": "screening", "check_types": ["sanctions", "pep", "adverse_media"]}
  ]
}

Simple Workflow

The Simple workflow provides basic identity verification for lower-risk scenarios.

Step	Type	Description	Required
1	`document`	Government-issued ID	Yes
2	`screening`	Basic watchlist check	Yes

Use Cases:

Low-value transactions
Non-regulated services
Age verification
Basic identity confirmation

API Configuration:

{
  "workflow_id": "wf_simple",
  "steps": [
    {"id": "document", "type": "document", "required": true},
    {"id": "screening", "type": "screening", "check_types": ["sanctions"]}
  ]
}

Configuring Workflow Steps

Step Types

Each step type has specific configuration options:

Document Step

{
  "id": "id_document",
  "type": "document",
  "config": {
    "accepted_types": ["passport", "drivers_license", "id_card"],
    "accepted_countries": ["US", "GB", "DE", "FR"],
    "require_back": false,
    "ocr_enabled": true,
    "fraud_detection": true
  }
}

Selfie Step

{
  "id": "selfie",
  "type": "selfie",
  "config": {
    "quality_threshold": 70,
    "face_match_threshold": 90,
    "max_attempts": 3
  }
}

Liveness Step

{
  "id": "liveness",
  "type": "liveness",
  "config": {
    "method": "passive",
    "confidence_threshold": 80,
    "anti_spoofing_enabled": true
  }
}

Address Step

{
  "id": "address",
  "type": "address",
  "config": {
    "accepted_documents": ["utility_bill", "bank_statement"],
    "max_age_days": 90,
    "verification_provider": "smarty"
  }
}

Screening Step

{
  "id": "screening",
  "type": "screening",
  "config": {
    "check_types": ["sanctions", "pep", "adverse_media"],
    "fuzzy_match_threshold": 85,
    "sources": ["ofac", "un", "eu", "hmt"]
  }
}

Step Dependencies

Steps can be configured with dependencies on previous steps:

{
  "steps": [
    {"id": "document", "type": "document"},
    {"id": "selfie", "type": "selfie", "depends_on": ["document"]},
    {"id": "liveness", "type": "liveness", "depends_on": ["selfie"]}
  ]
}

[Screenshot: Step configuration panel showing dependencies and thresholds]

Risk-Based Routing

Workflow rules determine what action to take based on verification results and risk assessment.

Routing Actions

Action	Description	Typical Trigger
`auto_approve`	Automatically approve applicant	Low risk, all checks pass
`manual_review`	Route to compliance queue	Medium risk or inconclusive
`auto_reject`	Automatically reject applicant	Policy violation, confirmed fraud
`escalate`	Route to senior compliance	High risk, sanctions hit
`hold`	Pause for additional information	Missing documentation

Workflow Rules Configuration

Rules are evaluated in priority order (highest priority first). The first matching rule determines the action.

Creating a Workflow Rule

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Auto-approve low risk",
    "description": "Automatically approve applicants with low risk and no hits",
    "conditions": {
      "risk_level": ["low"],
      "has_sanctions_hit": false,
      "has_pep_hit": false
    },
    "action": "auto_approve",
    "priority": 100,
    "is_active": true
  }'

Default Workflow Rules

TrustGate provides these default rules that can be customized:

Priority	Rule Name	Conditions	Action
1000	Escalate sanctions hits	`has_sanctions_hit: true`	`escalate`
800	Review high-risk countries	`country: [KP, IR, SY, MM, AF, YE]`	`manual_review`
500	Review high risk	`risk_level: [high, critical]`	`manual_review`
100	Auto-approve low risk	`risk_level: low, no hits`	`auto_approve`
0	Default manual review	(matches all)	`manual_review`

Rule Conditions

Available condition types for workflow rules:

Condition	Type	Example
`risk_level`	List of levels	`["high", "critical"]`
`risk_score_min`	Minimum score	`60`
`risk_score_max`	Maximum score	`30`
`country`	List of ISO codes	`["KP", "IR", "SY"]`
`has_sanctions_hit`	Boolean	`true`
`has_pep_hit`	Boolean	`true`
`has_adverse_media`	Boolean	`true`
`document_verified`	Boolean	`true`
`biometrics_passed`	Boolean	`true`

Rule Notifications

Rules can trigger notifications when matched:

{
  "name": "Alert on sanctions match",
  "conditions": {"has_sanctions_hit": true},
  "action": "escalate",
  "notify_on_match": true,
  "notification_channels": ["email", "slack", "webhook"],
  "assign_to_role": "senior_compliance"
}

[Screenshot: Workflow rules list showing priority order and match statistics]

Testing Workflow Rules

Before activating rules, test them against existing applicants:

# Test a rule against a specific applicant
curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules/{rule_id}/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"applicant_id": "app_abc123"}'

Response:

{
  "rule_id": "rule_xyz",
  "rule_name": "Auto-approve low risk",
  "applicant_id": "app_abc123",
  "matches": true,
  "condition_results": {
    "risk_level": {
      "expected": ["low"],
      "actual": "low",
      "matches": true
    },
    "has_sanctions_hit": {
      "expected": false,
      "actual": false,
      "matches": true
    }
  }
}

Workflow Versioning

When you modify a workflow, existing applicants continue using their assigned workflow version:

New applicants receive the current workflow version
In-progress applicants continue with their original version
Completed applicants retain their verification history

This ensures consistency and audit compliance.

Best Practices

1. Start with Default Workflows

Use the provided Standard, Enhanced, and Simple workflows as starting points, then customize based on your specific requirements.

2. Layer Risk Rules by Priority

Structure rules from most specific (high priority) to most general (low priority):

Priority 1000: Sanctions hit → Escalate (catches highest risk first)
Priority 500:  High risk country → Review
Priority 100:  Low risk + clean → Auto-approve
Priority 0:    Default → Manual review (catches everything else)

3. Test Before Activation

Always test new rules against a sample of applicants before activating in production.

4. Monitor Rule Performance

Track rule match statistics to ensure rules are working as expected:

GET /api/v1/workflows/rules/{rule_id}
# Response includes: times_matched, last_matched_at

5. Document Your Configuration

Maintain documentation of your workflow configuration for compliance audits.

API Reference

Workflow Rules Endpoints

Method	Endpoint	Description
`GET`	`/v1/workflows/rules`	List all workflow rules
`POST`	`/v1/workflows/rules`	Create a new rule
`GET`	`/v1/workflows/rules/{id}`	Get rule details
`PUT`	`/v1/workflows/rules/{id}`	Update a rule
`DELETE`	`/v1/workflows/rules/{id}`	Delete a rule
`POST`	`/v1/workflows/rules/{id}/test`	Test rule against applicant
`POST`	`/v1/workflows/rules/seed-defaults`	Seed default rules

Risk Assessment Endpoints

Method	Endpoint	Description
`GET`	`/v1/workflows/risk/{applicant_id}`	Get risk assessment
`POST`	`/v1/workflows/risk/{applicant_id}/recalculate`	Recalculate risk
`GET`	`/v1/workflows/risk/{applicant_id}/history`	Get assessment history

Next Steps

Document Verification - Configure document processing
Biometric Verification - Set up face matching
Verification Statuses - Understand status flows

What Are Workflows?​

How Workflows Work​

Workflow Assignment​

Step Execution​

Completion Flow​

Default Workflows​

Standard Workflow​

Enhanced Workflow​

Simple Workflow​

Configuring Workflow Steps​

Step Types​

Document Step​

Selfie Step​

Liveness Step​

Address Step​

Screening Step​

Step Dependencies​

Risk-Based Routing​

Routing Actions​

Workflow Rules Configuration​

Creating a Workflow Rule​

Default Workflow Rules​

Rule Conditions​

Rule Notifications​

Testing Workflow Rules​

Workflow Versioning​

Best Practices​

1. Start with Default Workflows​

2. Layer Risk Rules by Priority​

3. Test Before Activation​

4. Monitor Rule Performance​

5. Document Your Configuration​

API Reference​

Workflow Rules Endpoints​

Risk Assessment Endpoints​

Next Steps​

What Are Workflows?

How Workflows Work

Workflow Assignment

Step Execution

Completion Flow

Default Workflows

Standard Workflow

Enhanced Workflow

Simple Workflow

Configuring Workflow Steps

Step Types

Document Step

Selfie Step

Liveness Step

Address Step

Screening Step

Step Dependencies

Risk-Based Routing

Routing Actions

Workflow Rules Configuration

Creating a Workflow Rule

Default Workflow Rules

Rule Conditions

Rule Notifications

Testing Workflow Rules

Workflow Versioning

Best Practices

1. Start with Default Workflows

2. Layer Risk Rules by Priority

3. Test Before Activation

4. Monitor Rule Performance

5. Document Your Configuration

API Reference

Workflow Rules Endpoints

Risk Assessment Endpoints

Next Steps