Workflow Management

Workflows define the sequence of verification checks to perform for identity verification requests. This module allows you to create, configure, and manage custom verification workflows.

Overview

A workflow consists of:

• Basic Information: Name, description, and associated API client
• Document Types: Supported ID document types (e.g., Kenya National ID, Passport)
• Verification Checks: OCR, Face Matching, Liveness, Document Authenticity, etc.
• Confidence Thresholds: Minimum confidence scores required for each check
• Advanced Settings: Manual review queue, webhooks, custom metadata

Accessing Workflows

Navigate to Workflows in the sidebar of the Nafsi Console.

Creating a Workflow

Step 1: Basic Information

1. Click Create Workflow
2. Fill in the basic details:

Field	Description	Required
API Client	Select the client that will use this workflow	Yes
Client Secret	Enter the client secret for validation	Yes
Workflow Name	Descriptive name (e.g., "Basic KYC - Kenya")	Yes
Description	Purpose and use case	Optional

Important: Client Secret Validation

The client secret is required for:

1. Authentication: Validates that you own this API client
2. Refresh Token Generation: Generates a secure token for SDK/API integrations
3. Security: Ensures only authorized users can create workflows for this client

What happens during validation:

1. You enter client_id + client_secret
2. System validates credentials against database
3. Generates refresh token (JWT) for this workflow
4. Token attached to workflow for future API/SDK calls
5. Workflow becomes usable in integrations

Security Note:

• Client secret is validated but not stored with the workflow
• Only the generated refresh token is stored
• This token enables SDK/API authentication without exposing your secret

Example:

API Client: Production API Client
Client Secret: sk_live_abc123xyz789... (paste here)
Workflow Name: Standard KYC Workflow
Description: Basic identity verification for new customer onboarding

If validation fails:

• ❌ "Invalid client secret" → Check you pasted the correct secret
• ❌ "Client not found" → Ensure you selected the correct API client
• ❌ "Client inactive" → Activate your API client first

Step 2: Document Configuration

Select the document types this workflow will support:

Available Document Types:

• 🇰🇪 Kenya National ID
• 🇰🇪 Kenya Passport
• 🇳🇬 Nigeria National ID
• 🇬🇭 Ghana Voter ID
• 🇿🇦 South Africa ID
• 🇹🇿 Tanzania National ID
• 🇺🇬 Uganda National ID
• Generic Passport

Note: You can select multiple document types. The workflow will automatically detect the document type during verification.

Step 3: Verification Checks

Configure the verification checks to run. Each check has a unit cost:

Check	Description	Unit Cost	Required
OCR Extraction	Extract text from ID document	2 units	✅ Yes (Always first)
MRZ Parsing	Validate machine-readable zone	1 unit	No
Face Matching	Compare selfie to ID photo	3 units	No
Liveness Detection	AI-enhanced anti-spoofing	2 units	No
Document Authenticity	5-layer forgery detection	4 units	No
Sanctions Screening	Global watchlist check	1 unit	No
Age Verification	Verify person is 18+	1 unit	No
Address Verification	Cross-check with utility bill	5 units	No
Custom Checks	Your own verification webhooks	3 units	No

Drag and drop checks into the verification flow to define the sequence:

Flow Example:
1. OCR Extraction (required)
2. Face Matching
3. Liveness Detection
4. Document Authenticity
5. Sanctions Screening

Total Estimated Cost: 11 units per verification

Required Checks

• OCR Extraction is always required and must be the first check
• Required checks are locked (cannot be removed or reordered)
• Required checks are automatically added when you select document types

Custom Checks

You can add custom verification checks via webhooks:

1. Click Add Custom Check
2. Select a verification webhook you've created
3. The check will appear in the available checks list
4. Drag it into your workflow

Learn more about custom checks →

Step 4: Confidence Thresholds

Set minimum confidence scores for each check:

Check	Default	Range	Recommendation
Face Match	0.75	0.60 - 0.95	0.75 for standard, 0.85 for high-risk
Liveness	0.80	0.50 - 0.95	0.80 recommended
Document Authenticity	0.75	0.60 - 0.95	0.75 for most cases

How It Works:

• If a check's confidence is below the threshold, the verification fails
• If a check's confidence is above the threshold, the verification passes
• You can adjust thresholds based on your risk tolerance

Example Scenarios:

Use Case	Face Match Threshold	Liveness Threshold	Document Auth
Low-risk (social app)	0.70	0.75	0.70
Standard (banking)	0.75	0.80	0.75
High-risk (large loans)	0.85	0.90	0.85

Step 5: Advanced Settings (Optional)

Manual Review Queue

Enable manual review for low-confidence results:

• Enable Manual Review: Toggle ON
• Auto-decline below threshold: If OFF, sends to review queue instead of auto-failing
• Reviewer email: Email address to notify reviewers

How It Works:

If confidence < threshold:
  - Auto-decline OFF → Send to manual review queue
  - Auto-decline ON → Automatically fail verification

Webhook Configuration

Set a webhook URL to receive notifications for this specific workflow:

Webhook URL: https://your-app.com/webhooks/verification
Events:
  - verification.completed
  - verification.failed
  - verification.review_required

Learn more about webhooks →

Custom Metadata Fields

Add custom fields to include in verification responses:

{
  "customer_id": "string",
  "application_id": "string",
  "loan_amount": "number",
  "risk_category": "string"
}

These fields will be echoed back in the verification response.

Managing Workflows

Viewing Workflows

The workflows list shows:

Column	Description
Name	Workflow name
Document Types	Supported documents (with flags)
Checks	Number of enabled checks
Cost/Verification	Unit cost per verification
Status	Active / Draft / Archived
Actions	Edit / Duplicate / Archive / Test

Editing a Workflow

1. Click Edit on the workflow row
2. The wizard opens in edit mode
3. Make your changes:
   • ✅ You can add/remove optional checks
   • ✅ You can adjust thresholds
   • ✅ You can update advanced settings
   • ❌ You cannot change document types (create new workflow instead)
   • ❌ You cannot remove required checks
4. Click Update Workflow

Important: Changes to workflows are immediate and affect all future verifications.

Duplicating a Workflow

Quickly create a new workflow based on an existing one:

1. Click Duplicate on the workflow
2. The wizard opens with all settings pre-filled
3. Modify as needed (e.g., change thresholds for high-risk variant)
4. Save as a new workflow

Use Case: Create "Standard KYC" and "High-Risk KYC" workflows with different thresholds.

Archiving a Workflow

Archived workflows:

• Cannot be used for new verifications
• Existing verification data is preserved
• Can be reactivated later

1. Click Archive on the workflow
2. Confirm archival
3. Status changes to Archived

To reactivate: Click Activate on an archived workflow.

Testing a Workflow

Before going live, test your workflow:

1. Click Test on the workflow
2. Upload sample images:
   • Front ID
   • Back ID
   • Selfie
3. Click Run Test Verification
4. View detailed results:
   • Extracted data
   • Confidence scores for each check
   • Pass/fail status
   • Units consumed
   • Processing time

Note: Test verifications consume units.

Workflow Integration

Using Workflows in API Calls

curl -X POST https://api.nafsi.ai/v1/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "client_id": "86f59fee-df8a-11f0-8e0f-9ef6b0f7fa9e",
    "work_flow_id": "15311659-e749-11f0-8b8f-ce34decab3c1",
    "selfie_image_url": "data:image/jpeg;base64,...",
    "id_front_image_url": "data:image/jpeg;base64,...",
    "id_back_image_url": "data:image/jpeg;base64,...",
    "method": "process_idv"
  }'

Using Workflows in Web SDK

Nafsi.init({
    clientId: '86f59fee-df8a-11f0-8e0f-9ef6b0f7fa9e',
    workflowId: '15311659-e749-11f0-8b8f-ce34decab3c1', // Your workflow ID
    onSuccess: (result) => {
        console.log('Verification passed!', result);
    },
    onFailure: (error) => {
        console.error('Verification failed:', error);
    }
});

Business Rules

BR-WORKFLOW-001: Document Types

• At least one document type must be selected
• Document types cannot be changed after workflow creation
• To change document types, create a new workflow

BR-WORKFLOW-002: Required Checks

• OCR extraction is always required and must be first
• Required checks are locked (cannot be removed or reordered)
• Required checks auto-added when document type selected

BR-WORKFLOW-003: Flow Sequence

• Minimum 1 check (OCR)
• Maximum 10 checks per workflow
• Checks execute in defined sequence order
• If any check fails, subsequent checks are skipped

BR-WORKFLOW-004: Workflow Naming

• Name must be unique per client
• Length: 3-255 characters
• Must be descriptive of workflow purpose

BR-WORKFLOW-005: Edit Mode Protection

• Flow sequence preserved when switching tabs
• Available checks filtered by both id and component_id
• String normalization for ID comparison

Use Cases

Use Case 1: Basic KYC for Low-Risk Customers

Scenario: Social lending app, small loan amounts (< $100)

Configuration:

• Checks: OCR + Face Match
• Thresholds: Face Match 0.70
• Cost: 5 units per verification
• Manual Review: OFF (auto-decline)

Use Case 2: Standard KYC for Banking

Scenario: Digital bank, account opening

Configuration:

• Checks: OCR + Face Match + Liveness + Document Authenticity
• Thresholds: Face 0.75, Liveness 0.80, Doc Auth 0.75
• Cost: 11 units per verification
• Manual Review: ON (send low-confidence to review)

Use Case 3: High-Risk KYC for Large Loans

Scenario: Loan amounts > $10,000, high-risk customers

Configuration:

• Checks: All checks including Sanctions Screening
• Thresholds: Face 0.85, Liveness 0.90, Doc Auth 0.85
• Cost: 13 units per verification
• Manual Review: ON (all low-confidence results)

Use Case 4: Age Verification Only

Scenario: Age-restricted content (18+)

Configuration:

• Checks: OCR + Age Verification
• Thresholds: N/A (just check if DOB indicates 18+)
• Cost: 3 units per verification
• Manual Review: OFF

Monitoring Workflow Performance

View Analytics

Navigate to Dashboard → Verification Survey tab to see:

• Success Rate by Workflow: Which workflows have highest pass rate
• Average Confidence by Workflow: Are thresholds too strict/lenient?
• Processing Time by Workflow: Performance metrics
• Units Consumption by Workflow: Cost tracking

Optimization Tips

1. Monitor Success Rates: If success rate is too low, consider:

   • Lowering confidence thresholds
   • Removing optional checks
   • Enabling manual review

2. Balance Cost vs. Accuracy:

   • More checks = higher cost but higher confidence
   • Fewer checks = lower cost but may miss fraud

3. A/B Testing:

   • Create two workflows with different thresholds
   • Compare success rates and fraud rates
   • Optimize based on data

Best Practices

1. Start Conservative: Begin with standard thresholds (0.75, 0.80) and adjust based on results
2. Use Manual Review: For borderline cases, human review is valuable
3. Document Your Workflows: Use clear names and descriptions
4. Test Before Production: Always test with sample data first
5. Monitor and Iterate: Regularly review performance and adjust
6. Separate Workflows for Different Risk Levels: Don't use one-size-fits-all

Troubleshooting

Issue: High Failure Rate

Possible Causes:

• Thresholds too strict
• Poor image quality from users
• Wrong document type selected

Solutions:

• Lower thresholds by 0.05
• Add user guidance for better photos
• Enable manual review for borderline cases

Issue: Workflow Not Appearing in SDK/API

Possible Causes:

• Workflow is in Draft/Archived status
• Wrong client ID

Solutions:

• Ensure workflow status is Active
• Verify client ID matches the one used in workflow

Issue: "Flow Already Loaded" Error in Edit Mode

Possible Causes:

• Switching between tabs too quickly

Solutions:

• Refresh the page
• Clear browser cache
• Contact support if persists

API Reference

For detailed API documentation, see:

• Workflow APIs
• Verification APIs

Next Steps

• Create Custom Verification Checks

• Set Up Webhooks for Workflow Events

• Monitor Workflow Performance

Support

Need help with workflows?

• 📧 Email: support@nafsi.ai
• 💬 Live Chat: Available in console
• 📚 Documentation: https://docs.nafsi.ai

---

Last Updated: 2026-01-28