Skip to main content

SmartEnroll: Self-Hosted

The SmartEnroll API provides programmatic access to all SmartEnroll functionality, allowing you to build custom KYC and onboarding flows that integrate seamlessly with your existing systems. This solution is perfect for businesses that need more control over the user experience or want to integrate onboarding into their existing applications.

Overview​

The SmartEnroll API enables you to create and manage KYC (Know Your Customer) projects programmatically, offering the same powerful verification capabilities as the SmartEnroll interface but with complete API control. Version 3 introduces a streamlined, step-by-step configuration process that makes it easier to build custom onboarding flows while maintaining flexibility and control.

Whether you're onboarding individuals (personal KYC) or businesses (business KYB), the SmartEnroll API provides a structured approach to collecting user information, verifying documents, performing biometric checks, and integrating with your existing systems.

Key Features​

Project Management

Create and manage KYC projects with full control over configuration, branding, and verification steps.

Project Flows

Configure verification flows with document scanning, biometric verification, and background checks.

Custom Branding

Fully customizable project branding to match your brand identity and user experience requirements.

API Integration

Seamless integration with your existing systems through RESTful APIs and webhook notifications.

Real-time Updates

Step-by-step project configuration with real-time updates and validation feedback.

Security First

Enterprise-grade security with JWT authentication and comprehensive data protection compliance.

Getting Started​

Authentication​

All API requests require a valid JWT token. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Base URLs​

  • Production: https://api.verifik.co
  • Staging: https://staging-api.verifik.co
  • Development: https://dev-api.verifik.co
Environment Selection

Use the appropriate base URL based on your environment. All examples in this documentation use the production URL.

Quick Start Example​

Here's a simple example of how to list all projects using the API:

Loading...

API Resources​

The SmartEnroll API provides two main resources:

Projects​

Manage your KYC projects with complete control over configuration, branding, and verification settings.

Project Flows​

Configure verification flows and manage project-specific settings.

Response Format​

All API responses follow a consistent format:

Success Response​

{
    "data": {
        // Response data
    },
    "total": 0,
    "limit": 0,
    "page": 0,
    "pages": 0
}

Error Response​

{
    "message": "Error description",
    "code": "ERROR_CODE"
}

Rate Limits​

  • Project Operations: 100 requests per minute per user
  • Project Flow Operations: 50 requests per minute per user
  • Document Verification: 20 requests per minute per user
  • Biometric Verification: 10 requests per minute per user
  • Background Checks: 5 requests per minute per user

Building a KYC Project​

SmartEnroll Version 3 provides a structured, 6-step workflow for creating personal KYC (Know Your Customer) projects. Each step builds upon the previous one, allowing you to configure your onboarding flow progressively.

Understanding Project Targets​

Before you begin, it's important to understand the two types of projects:

  • Personal (KYC) - For onboarding individual users
  • Business (KYB) - For onboarding companies and their legal representatives (covered in separate documentation)

This guide focuses on Personal KYC projects.

Step 1: Basic Setup​

The first step establishes the foundation of your KYC project. This includes basic project information, compliance details, and data protection settings required by privacy regulations.

What You'll Configure​

  • Project Name - A descriptive name for your KYC project
  • Allowed Countries - Countries where users can complete onboarding
  • Contact Email - Email address for project-related communications
  • Privacy & Terms URLs - Links to your privacy policy and terms of service
  • Data Protection Information - Details about your Data Protection Officer (required for GDPR compliance)

Example: Create a Basic Project​

Loading...
Data Protection Information

The dataProtection field is required for compliance with privacy regulations like GDPR. Ensure you provide accurate information about your Data Protection Officer or privacy contact.

Step 2: Sign-Up Form​

Configure what information to collect from users when they begin the onboarding process. This step determines the initial data collection before document verification.

What You'll Configure​

  • Full Name Collection - Whether to collect user's full name (required)
  • Name Format - Collect name as one field or separate first/last name fields
  • Email Collection - Whether to collect and verify email addresses
  • Email Gateway - How to send verification emails (Mailgun or none)
  • Phone Collection - Whether to collect and verify phone numbers
  • Phone Gateway - How to send verification codes (SMS, WhatsApp, both, or none)
  • Additional Fields - Custom fields specific to your business needs
  • Privacy & Terms Display - Whether to show consent checkboxes

Example: Configure Sign-Up Form​

Loading...
Name Format Options
  • together - Single field for full name (e.g., "John Doe")
  • separate - Separate fields for first and last name

Choose based on your regional requirements and user experience preferences.

Step 3: Document Verification​

Configure how users will verify their identity documents. This step is crucial for KYC compliance and identity verification.

What You'll Configure​

  • Document Step Requirement - Whether document verification is mandatory, optional, or skipped
  • Attempt Limit - Maximum number of upload attempts (1-5)
  • Document Types - Which documents to accept per country (government ID, passport, driver's license)
  • Verification Methods - How documents will be validated (scanning, upload, or both)
  • Advanced Verification - Additional checks like information verification, screening, or criminal history

Document Categories​

For personal KYC, you can configure these document types:

  • government_id - Government-issued identification cards
  • passport - International passports
  • license - Driver's licenses

Example: Configure Document Verification​

Loading...
Document Types Per Country

Each country must have at least one active document configuration when the document step is not skipped. Configure document types based on what's commonly used in each country.

Step Requirements​

  • mandatory - Users must complete document verification to proceed
  • optional - Users can choose to skip document verification
  • skip - Document verification is not included in the flow

Step 4: Liveness Detection​

Configure biometric verification to ensure users are physically present during onboarding. This step uses facial recognition and liveness detection to prevent fraud.

What You'll Configure​

  • Liveness Step Requirement - Whether biometric verification is mandatory, optional, or skipped
  • Attempt Limit - Maximum number of liveness verification attempts (1-5)
  • Liveness Score - Minimum score to confirm the user is live (0.52 - 0.90)
  • Comparison Score - Minimum score to match face with document photo (0.70 - 0.95)
  • Search Mode - Speed vs accuracy trade-off (FAST or ACCURATE)

Example: Configure Liveness Detection​

Loading...
Liveness Scores
  • minScore (0.65 recommended) - Lower scores work with low-quality cameras but may increase false positives
  • searchMinScore (0.80 recommended) - Higher scores provide better face-to-document matching but require better image quality

Start with recommended values and adjust based on your security requirements and user experience feedback.

Search Modes​

  • FAST - Optimized for speed, suitable for most use cases
  • ACCURATE - Slower but more precise, recommended for high-security applications

Step 5: Integrations​

Connect your KYC project to external systems, configure webhooks for real-time notifications, and set up post-onboarding redirects.

What You'll Configure​

  • Redirect URL - Where to send users after completing onboarding (required)
  • Webhook - Endpoint to receive real-time onboarding events
  • Blacklist Integration - Connect to external databases to prevent enrollment
  • API Integration - Link to your customer database for data validation

Example: Configure Integrations​

Loading...
Blacklist Integration

The blacklist feature allows you to connect an external database. Users found in this database will be prevented from completing onboarding. Set source to "API" or "CSV" and configure the appropriate connection details.

Integration Sources​

  • NONE - No external integration
  • API - Connect to a RESTful API endpoint
  • CSV - Upload a CSV file (coming soon)

Integration Strategies​

  • none - Allow all users to enroll
  • blacklist - Prevent users found in external database from enrolling

Step 6: User Interface Customization​

Customize the visual appearance of your onboarding flow to match your brand identity. This step is optional but recommended for a seamless user experience.

What You'll Configure​

  • Logo - Your company logo (displayed at the top)
  • Background Color - Main background color
  • Button Color - Primary button color
  • Button Text Color - Text color for buttons
  • Title Color - Color for headings and titles
  • Text Color - Color for body text
  • Image - Background or decorative image
  • Image Background Color - Background color for the image area

Example: Configure Branding​

Loading...
Color Guidelines
  • Use high contrast between text and backgrounds for accessibility
  • Test your color scheme on both desktop and mobile devices
  • Ensure button colors stand out from the background
  • Consider your brand guidelines when choosing colors

Complete Project Example​

Here's a complete example showing how to create a fully configured KYC project in a single request:

Loading...

Project Lifecycle Management​

Activating Your Project​

Once you've configured all steps, change the project status to make it live:

Loading...

Project Status Values​

  • draft - Project is being configured, not accessible to end users
  • active - Project is live and accepting user enrollments
  • paused - Project is temporarily disabled, no new enrollments accepted
Before Activating

Ensure all required steps are properly configured and tested before setting status to "active". Users will not be able to complete onboarding if required steps are missing or misconfigured.

Integration Patterns​

Progressive Configuration​

Build your project step-by-step, matching the SmartEnroll interface workflow:

  1. Create the project with basic information
  2. Configure sign-up form fields
  3. Set up document verification
  4. Enable liveness detection
  5. Connect integrations and webhooks
  6. Customize branding and appearance
  7. Activate the project

This approach provides better error handling and validation at each step.

Single-Request Configuration​

Create a complete project in one API call if you have all configuration details prepared. This is ideal for:

  • Automated project creation
  • Template-based deployments
  • Migration from other systems
Best Practice

Use the progressive approach when building projects manually or through a user interface. Use the single-request approach for automation and templates.

Support​

For technical support and API documentation assistance:

Getting Help

When contacting support, include your project ID, API endpoint, and request/response details for faster assistance.

Important

Always test your integration thoroughly in the development environment before deploying to production.