KYC

Templates

KYC templates configure how user identity verification is performed. Templates determine which checks to run, which documents to accept, and how results are decided.

KYC Template Configuration

Every KYC template includes these key configuration areas:

Entity Type:

• Must be set to USER for KYC verifications
• Cannot use business templates for user verification

Workflow Association:

• Each template links to one verification workflow
• Workflows define the sequence of checks (document verification, biometrics, AML, government lookups, etc.)
• Common KYC workflows include:
  • Document verification + face match + liveness
  • Government ID lookup only
  • Document + AML screening
  • Multi-step verification with follow-on documents

Callback Configuration:

• callback_url: Receives complete verification results when processing finishes
• events_callback_url: Receives real-time event notifications during verification
• Can be overridden per session for flexibility

UI Customization:

• theme_options: Branding (colors, fonts, logo)
• redirect_uri: Where to send users after completing verification
• Custom email templates for verification invitations

See the API Reference for complete template configuration options. TODO(Rajat): Add link>

Configuring Required Fields

Templates specify which user data fields are required vs optional:

Common Required Fields:

• first_name, last_name
• date_of_birth (format: YYYY-MM-DD)
• country or identity_country_code (2-letter ISO code)

Common Optional Fields:

• middle_name
• phone_number (E.164 format recommended)
• email_address
• address (street, city, state, zip, country)
• ip_address

Field Validation:

• Date of birth must be YYYY-MM-DD format
• Phone numbers validated for format
• Email addresses validated for format
• Country codes must be 2-letter ISO 3166-1 alpha-2 codes

Required Field Checking: Templates can enforce field requirements before verification starts. Missing required fields cause immediate validation errors (400 Bad Request).

Best Practices:

• Only require fields you actually need for verification
• Use optional fields for data enrichment
• Consider user experience - fewer required fields = easier onboarding
• Validate data client-side before sending to API

Document Types & Countries

KYC templates support identity documents from 40+ countries.

Supported Document Types:

Country-Specific Documents:

TODO(Rajat): Add link to supported KYCs-->

Configuring Accepted Documents: Templates specify which document types are accepted per country using identity bundles:

• Define accepted documents for each supported country
• Restrict to specific document types if needed
• Enable "any document" mode for maximum flexibility

Document Front & Back: Some documents require both front and back images (e.g., driver's license, national ID). The verification flow automatically requests both sides when needed.

Verification Options

Templates support various verification options to customize the verification flow:

Liveness Check:

• enable_liveness_check: Require liveness detection during selfie capture
• Prevents photo-of-photo fraud
• Can be required or optional

Age Restrictions:

• minimum_age: Minimum age requirement (e.g., 18, 21)
• Automatically calculates age from date of birth
• Triggers AGE_UNDER_18 warning if below minimum

Document Expiry:

• allow_expired_documents: Whether to accept expired identity documents
• Default behavior: Expired documents trigger DOCUMENT_EXPIRED → DECLINED
• Can be overridden for specific use cases

Face Matching:

• face_match_threshold: Confidence threshold for selfie-to-document photo matching (0.0 - 1.0)
• Higher threshold = stricter matching
• Lower threshold = more lenient (may increase false positives)

AML Screening:

• aml_monitoring_enabled: Enable ongoing AML monitoring after verification
• Periodic checks against sanctions/PEP lists
• Notifications when new matches found

Example Configuration:

{
  "verification_options": {
    "enable_liveness_check": true,
    "minimum_age": 18,
    "allow_expired_documents": false,
    "face_match_threshold": 0.85
  }
}

These options can be set at template level or overridden per session.

Session API & Lifecycle

User verification sessions represent individual verification attempts. Understanding session types and lifecycle helps you choose the right integration pattern.

Verification Patterns

AiPrise supports three main verification patterns for KYC:

1. API-Initiated Verification (Server-to-Server)

Pattern: Your backend sends user data directly to AiPrise API for verification.

When to Use:

• You already have user data (collected during sign-up)
• Server-side verification flow
• Batch verification processing
• Background verification checks

Endpoint: POST /api/v1/verify/run_user_verification

Flow:

Your Backend → AiPrise API (with user data) → Verification Executes → Results via Webhook/API

Characteristics:

• Synchronous or asynchronous workflow execution
• User never interacts with AiPrise UI
• You handle document collection and submission
• Results returned immediately (sync) or via webhook (async)

See API Reference: run_user_verification

2. Hosted UI Verification (End-User Flow)

Pattern: Generate a verification URL and send users to AiPrise's hosted verification interface.

When to Use:

• User self-service verification
• Don't want to build document capture UI
• Need liveness detection and biometric capture
• Want pre-built mobile-optimized verification flow

Endpoint: POST /api/v1/verify/get_user_verification_url

Flow:

Your Backend → Generate URL → Send to User → User Completes Verification → Results via Webhook

Characteristics:

• AiPrise handles entire user experience
• Built-in document capture, liveness checks, progress tracking
• Mobile and desktop optimized
• Redirects user back to your app when complete
• Results delivered via webhook

URL Configuration:

• Optional user data pre-filling (name, DOB, etc.)
• Custom branding via theme_options
• redirect_uri: Where to send user after completion
• Session expiration (default: 24 hours)

See API Reference: get_user_verification_url

3. SDK Integration (Mobile/Web Apps)

Pattern: Embed verification directly into your mobile app or web app using AiPrise SDKs.

When to Use:

• Native mobile app experience
• Full control over UI/UX
• Custom verification flows
• Seamless in-app verification

Endpoint: POST /api/v1/verify/get_user_verification_url_for_sdk

Flow:

Your App → Get Session ID → SDK Handles Capture → Submit to AiPrise → Results via Webhook

Characteristics:

• Native camera integration
• Custom UI around verification steps
• Progress tracking within your app
• Real-time validation feedback

See SDK Documentation: Mobile SDK Guide

Session Lifecycle

All verification sessions progress through these states:

NOT_STARTED → SUBMITTED → RUNNING → COMPLETED
                                   ↘ PENDING → COMPLETED
                                   ↘ FAILED

State Definitions:

Run Status vs Result Status:

• Run Status: Execution state (NOT_STARTED, RUNNING, COMPLETED, etc.)
• Result Status: Verification decision (APPROVED, DECLINED, REVIEW, UNKNOWN)

A session can be COMPLETED with various result statuses:

• COMPLETED + APPROVED → User passed verification
• COMPLETED + DECLINED → User failed verification
• COMPLETED + REVIEW → Manual review required
• COMPLETED + UNKNOWN → Information-only checks (no decision)

When to Use Each Endpoint

Choose the right endpoint based on your use case:

API-Initiated Flow:

• Use when you have user data already
• Full control over process
• Can be synchronous or async

Hosted UI Flow:

• Use for self-service verification
• Minimal integration effort
• Best user experience out-of-box

SDK Flow:

• Use for native app integration
• Custom UI/UX requirements
• Real-time feedback during capture

Profile Flow:

• Use for ongoing customer relationships
• Enables re-verification and monitoring
• Best for regulated industries

Handling Results

Verification results include comprehensive data about the verification outcome:

Key Result Fields:

• verification_session_id: Unique session identifier
• status: Run status (COMPLETED, FAILED, etc.)
• verification_result: Decision (APPROVED, DECLINED, REVIEW, UNKNOWN)
• warnings: Array of warning codes generated during verification
• id_info: Extracted document data (name, DOB, document number, etc.)
• face_info: Face matching results and confidence scores
• aml_info: AML screening results (if enabled)
• lookup_info: Government database lookup results (if performed)

Result Delivery Methods:

1. Synchronous Response (API-initiated only):

   • Results returned immediately in API response
   • Only for sync workflows
   • Use for simple, fast checks

2. Webhook Callback:

   • Results posted to callback_url
   • Supports both sync and async workflows
   • Recommended for all flows
   • See Callbacks & Events section

3. Polling (not recommended):

   • Call GET /get_user_verification_result/{session_id}
   • Less efficient than webhooks
   • Only use if webhooks not possible

Best Practices:

• Always use webhooks for result delivery
• Store verification_session_id for future reference
• Check both status and verification_result fields
• Review warnings array to understand what checks flagged
• Handle all three outcomes: APPROVED, DECLINED, REVIEW

Error Handling & Retries

Verification can fail at various stages. Handle errors gracefully:

Common Failure Scenarios:

1. Validation Errors (400 Bad Request):

• Missing required fields
• Invalid data format (date, phone, email)
• Template not found
• Document type not supported for country

Solution: Fix request payload and retry immediately.

2. Workflow Failures (status = FAILED):

• External provider timeout
• Configuration error
• Runtime exception

Solution: Review error logs, fix configuration if needed, use retry endpoint.

3. Verification Declined (DECLINED result):

• Document expired, fake ID, face mismatch
• Not a system failure - user failed verification

Solution: Handle according to business logic (reject user, request manual review, ask for different document).

Retry Strategies:

Manual Retry Endpoint:

POST /api/v1/verify/retry_user_verification

Use when:

• Workflow FAILED due to transient error
• Provider timeout occurred
• Want to re-run same session with updated data

Create New Session: Better approach for:

• User wants to try different document
• Significant time passed
• Need different template/workflow

Retry Best Practices:

• Don't retry validation errors - fix the payload
• Use exponential backoff for provider failures
• Limit retries to avoid rate limits
• Create new session if user is re-attempting after failure

Handling REVIEW Status: Cases marked for manual review should be:

• Queued for human review in your dashboard
• Notified to compliance team
• User notified of pending status
• Decision made within SLA timeframe

User Profile (KYC Enhanced)

User profiles provide persistent identity storage for ongoing customer relationships. Profiles enable re-verification, AML monitoring, and compliance tracking.

Profile-Based Verification

Profiles are an alternative to independent verification sessions.

Profile Pattern:

Create Profile → Add Documents → Run Verification → Update Profile → Re-verify

Session Pattern:

Create Session → Run Verification → Done (no persistence)

Key Differences:

Profile Lifecycle

Profiles follow a multi-stage lifecycle:

1. Creation

Create a profile with basic user information:

Endpoint: POST /api/v1/verify/create_user_profile

Required Data:

• Name (first, last, optionally middle)
• Optional: DOB, email, phone, address
• client_reference_id: Your internal user ID

Profile ID:

• Returns external_user_profile_id (UUID)
• Store this ID in your database
• Use for all future operations on this profile

2. Document Addition

Add identity documents to the profile:

Endpoint: POST /api/v1/verify/add_user_document

Document Management:

• Upload multiple documents (passport, driver's license, etc.)
• Documents persist with profile
• Each document gets unique document_id
• Can add/remove documents over time

Document Metadata:

• document_type: PASSPORT, DRIVERS_LICENSE, NATIONAL_ID, etc.
• File upload (JPEG, PNG, PDF)
• Front and back images if applicable

3. Verification Execution

Run verification on the profile:

Endpoint: POST /api/v1/verify/run_verification_for_user_profile_id

Parameters:

• external_user_profile_id: Profile to verify
• template_id: Which verification workflow to run
• Optional: callback_url, verification_options

Multiple Verifications:

• Can run multiple verification sessions on same profile
• Each verification creates new session
• All sessions linked to profile
• History preserved for audit trail

4. Profile Updates

Update profile data without re-verification:

Endpoint: PATCH /api/v1/verify/update_user_profile

Updatable Fields:

• Email address
• Phone number
• Address
• Custom metadata

When to Update vs Re-verify:

• Update only: Contact info changed, no re-verification needed
• Update + Re-verify: New address requires proof of address verification
• Re-verify without update: Periodic compliance check on existing data

5. Re-verification

Run new verification on existing profile:

Use Cases:

• Periodic compliance requirements (annual KYC refresh)
• Document expired, need new document
• Higher risk tier requires additional checks
• AML monitoring triggered alert

Process:

• Upload new documents if needed
• Run verification with same or different template
• New verification session created
• Previous verification history preserved

6. Deactivation

Mark profile as deactivated when relationship ends:

Result Status: DEACTIVATED

Use Cases:

• Customer closed account
• User requested data deletion
• Compliance retention period ended

Note: Deactivation is status change, not deletion. Actual data deletion handled separately per data retention policy.

Use Cases

When to Use Profiles:

✅ Financial Services:

• Customer accounts requiring periodic KYC updates
• AML monitoring and sanctions screening
• Audit trail for regulatory compliance
• Transaction monitoring integration

✅ Healthcare:

• Patient identity verification
• Ongoing eligibility verification
• HIPAA compliance requirements
• Multi-visit identity confirmation

✅ Gaming/Gambling:

• Player verification and age validation
• Responsible gaming monitoring
• Regulatory compliance (license requirements)
• Re-verification on withdrawal requests

✅ Cryptocurrency:

• Exchange account verification
• Enhanced due diligence for high-value users
• Travel rule compliance
• Ongoing sanctions screening

✅ Marketplaces:

• Seller verification
• Trust and safety programs
• Repeat customer identification
• Fraud prevention across transactions

When NOT to Use Profiles:

❌ Guest Checkout:

• One-time purchase verification
• No ongoing relationship
• Minimal data retention needs

❌ Event Access:

• Single event ticket verification
• Age verification at entry
• No future verification needed

❌ Simple Age Gates:

• Basic age verification
• No compliance requirements
• One-time check sufficient

Profile vs Session Trade-offs

Choose Profiles When:

• You need AML monitoring
• Periodic re-verification required
• Compliance audit trail important
• Relationship spans months/years
• Multiple verification types needed
• Document updates expected

Choose Sessions When:

• One-time verification sufficient
• No ongoing monitoring needed
• Simple onboarding flow
• Minimal data retention preferred
• Lower complexity desired
• Guest/anonymous users

Cost Considerations:

• Profiles: Small storage cost + verification costs
• Sessions: Only verification costs
• AML monitoring: Additional ongoing cost

Complexity:

• Profiles: Higher integration complexity
• Sessions: Lower integration complexity

Data Retention:

• Profiles: Long-term storage
• Sessions: Short-term or no storage after verification

Warning Codes

KYC verifications generate warning codes based on document quality, biometric checks, data validation, and fraud indicators.

KYC-Specific Warnings

These warning codes are commonly encountered in user verification:

Document Quality:

• UNRECOGNIZED_DOCUMENT → REVIEW - Document type not identified
• DOCUMENT_EXPIRED → DECLINED - Identity document is expired
• DOCUMENT_CROPPED → REVIEW - Document edges not fully visible
• IMAGE_TOO_BLURRY → REVIEW - Document image quality insufficient
• GLARE_DETECTED → REVIEW - Glare obscuring document details
• DOCUMENT_DAMAGED → REVIEW - Physical damage to document

Biometric/Face Matching:

• FACE_NOT_MATCH → DECLINED - Selfie doesn't match document photo
• FACE_MATCH_LOW_CONFIDENCE → REVIEW - Face match confidence below threshold
• LIVENESS_CHECK_FAILED → DECLINED - Liveness detection failed
• NO_FACE_FOUND → REVIEW - No face detected in selfie
• MULTIPLE_FACES_DETECTED → REVIEW - Multiple faces in selfie image
• DOCUMENT_FACE_NOT_FOUND → REVIEW - No face on document

Data Validation:

• NAME_VERIFICATION_FAILED → APPROVED - Name mismatch (document vs provided)
• BIRTH_DATE_MISMATCH → APPROVED - DOB mismatch (document vs provided)
• ID_COUNTRY_MISMATCH → DECLINED - Document country doesn't match expected
• ID_TYPE_MISMATCH → REVIEW - Document type doesn't match expected
• ADDRESS_MISMATCH → APPROVED - Address doesn't match document

Missing Data:

• MISSING_EXPIRY_DATE → REVIEW - Cannot read expiry date
• MISSING_DOCUMENT_NUMBER → REVIEW - Cannot read document number
• MISSING_BIRTH_DATE → APPROVED - Cannot read birth date
• MISSING_NAME → REVIEW - Cannot read name on document
• MISSING_ADDRESS → APPROVED - Cannot read address

Fraud Indicators:

• FAKE_ID → REVIEW - Document appears to be fake/sample
• IMAGE_FORGED_EDITED → REVIEW - Document shows signs of editing
• DOCUMENT_PHOTO_OF_PHOTO → REVIEW - Document is photo of photo
• SCREEN_DETECTED → REVIEW - Document photo taken from screen
• ARTIFICIAL_IMAGE → REVIEW - Artificially generated image detected

Age Verification:

• AGE_UNDER_18 → REVIEW - User is under 18 (or configured minimum age)
• FACE_AGE_MISMATCH → APPROVED - Facial age analysis doesn't match stated age

Common Scenarios

Scenario 1: Expired Driver's License

• Warning: DOCUMENT_EXPIRED
• Default Result: DECLINED
• Handling: Ask user for valid ID or enable allow_expired_documents in template

Scenario 2: Blurry Document Photo

• Warning: IMAGE_TOO_BLURRY
• Default Result: REVIEW
• Handling: Manual review to determine if readable, or ask user to retake photo

Scenario 3: Face Match Failure

• Warning: FACE_NOT_MATCH
• Default Result: DECLINED
• Handling: Possible fraud, reject or request manual review with additional verification

Scenario 4: Missing Address

• Warning: MISSING_ADDRESS
• Default Result: APPROVED
• Handling: Address is optional for most KYC, can continue or collect separately

Scenario 5: Liveness Check Failed

• Warning: LIVENESS_CHECK_FAILED
• Default Result: DECLINED
• Handling: Likely fraud (photo of photo), reject or escalate to fraud team

Scenario 6: Name Mismatch

• Warning: NAME_VERIFICATION_FAILED
• Default Result: APPROVED
• Handling: Common with nicknames, middle names - review manually or auto-approve

Scenario 7: Underage User

• Warning: AGE_UNDER_18
• Default Result: REVIEW
• Handling: Depends on your age requirement - can override to DECLINED if 18+ required

Customizing for KYC

Override warning codes in your template to match your risk tolerance:

High-Security KYC (Banking, Crypto):

{
  "custom_warning_codes": {
    "NAME_VERIFICATION_FAILED": "DECLINED",
    "BIRTH_DATE_MISMATCH": "DECLINED",
    "FACE_MATCH_LOW_CONFIDENCE": "DECLINED",
    "IMAGE_TOO_BLURRY": "DECLINED",
    "DOCUMENT_CROPPED": "DECLINED",
    "MISSING_DOCUMENT_NUMBER": "DECLINED"
  }
}

Standard KYC (Fintech, Healthcare):

{
  "custom_warning_codes": {
    "NAME_VERIFICATION_FAILED": "REVIEW",
    "BIRTH_DATE_MISMATCH": "REVIEW",
    "MISSING_ADDRESS": "APPROVED",
    "IMAGE_TOO_BLURRY": "REVIEW"
  }
}

Lenient KYC (Gaming, Social):

{
  "custom_warning_codes": {
    "DOCUMENT_CROPPED": "APPROVED",
    "MISSING_ADDRESS": "APPROVED",
    "MISSING_BIRTH_DATE": "APPROVED",
    "NAME_VERIFICATION_FAILED": "APPROVED"
  }
}

Age-Restricted Services (21+):

{
  "custom_warning_codes": {
    "AGE_UNDER_18": "DECLINED",
    "MISSING_BIRTH_DATE": "DECLINED",
    "DOCUMENT_EXPIRED": "DECLINED"
  }
}

Best Practices:

• Start with default mappings and adjust based on actual verification results
• Monitor decline rates - overly strict settings hurt conversion
• Balance fraud prevention with user experience
• Different templates for different risk tiers
• Test changes in sandbox before production

Next Steps

Now that you understand KYC verification:

• KYB (Businesses): Learn about business verification with UBOs
• Callbacks & Events: Set up webhooks for verification results
• API Reference: Detailed API endpoint documentation
• Warning Codes: Complete list of warning codes and meanings

Ready to verify users? Check the API Reference for endpoint details and code examples!