Overview

Introduction

AiPrise is a comprehensive identity verification platform that provides KYC (Know Your Customer), KYB (Know Your Business), and AML (Anti-Money Laundering) screening services. Our API enables you to verify users and businesses across 40+ countries with government registry connections and 35+ data provider integrations.

Key Capabilities:

• User Verification (KYC): Verify individual identities using government IDs, biometric checks, document verification, and liveness detection
• Business Verification (KYB): Verify business entities, beneficial owners, officers, and company documents
• AML Screening: Screen against sanctions lists, PEP databases, and watchlists
• Government Registry Checks: Direct connections to government databases for real-time verification
• Multi-Country Support: Verify identities in 40+ countries with localized document support

Two Verification Patterns:

1. Independent Sessions: One-time verification requests ideal for onboarding flows
2. Profile-Based Verification: Persistent user/business profiles for ongoing monitoring and re-verification

For step-by-step onboarding flows, API walkthroughs, and authentication setup, see the Guides section.

Environments

AiPrise provides two isolated environments for development and production use.

Sandbox Environment

Base URL: https://api-sandbox.aiprise.com/api/v1/

The Sandbox environment is designed for:

• Development and integration testing
• Testing verification workflows without charges
• Experimenting with different configurations
• Training and demos

Sandbox Characteristics:

• Isolated database (data does not mix with production)
• Test mode for certain providers (may return mock data)
• No charges for API calls
• Full feature parity with production
• Separate API keys from production

Use Sandbox For:

• Initial integration development
• Testing edge cases and error scenarios
• Validating webhook implementations
• QA and staging environments

Production Environment

Base URL: https://api.aiprise.com/api/v1/

The Production environment is for:

• Live user and business verifications
• Real provider checks with actual data
• Billable transactions

Production Characteristics:

• Live data and real verification results
• Charges apply based on your pricing plan
• Higher rate limits available
• Production-grade SLAs
• Separate API keys from sandbox

Use Production For:

• Live application traffic
• Real customer verifications
• Compliance and regulatory checks

Environment Isolation

• Data is completely isolated between environments
• API keys from one environment do not work in the other
• Templates and workflows are environment-specific
• User profiles and verification sessions are separate

Promoting from Sandbox to Production:

1. Test your integration thoroughly in Sandbox
2. Generate a Production API key
3. Update your configuration to use Production base URL and API key
4. Verify webhook endpoints work with production traffic
5. Monitor initial production verifications closely

API Design Principles

AiPrise follows RESTful API design principles for consistency and ease of integration.

Request Format

All API requests use JSON format:

Content-Type: application/json

HTTP Methods

AiPrise uses standard HTTP methods semantically:

• POST: Create resources or trigger actions (run verifications, create profiles)
• GET: Retrieve resources (get verification results, fetch profiles)
• PATCH: Update existing resources (update profiles, modify verification results)
• DELETE: Remove resources (delete profiles, remove documents)

Response Format

All successful responses return JSON with HTTP 200 status:

{
  "verification_session_id": "uuid-here",
  "status": "completed",
  "aiprise_summary": {
    "verification_result": "approved"
  }
}

HTTP Status Codes

Error Responses

Error responses include a descriptive message:

{
  "message": "Invalid date_of_birth format. Expected YYYY-MM-DD",
  "error_code": "VALIDATION_ERROR"
}

Pagination

List endpoints support pagination using query parameters:

GET /api/v1/verify/get_user_data?page=1&page_size=50

Pagination Parameters:

• page: Page number (1-indexed)
• page_size: Number of items per page (default: 50, max: 100)

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 250,
    "total_pages": 5
  }
}

Rate Limits

AiPrise implements rate limiting to ensure fair usage and platform stability.

Rate Limit Tiers

Rate limits vary by endpoint. Representative limits include:

Note: Rate limits are applied per API key and are subject to your plan tier.

Read-oriented endpoints (for example, GET /get_user_verification_result) inherit standard application limits and are monitored as part of your overall usage.

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "message": "Rate limit exceeded. Retry after 45 seconds.",
  "retry_after": 45
}

Best Practices:

1. Implement exponential backoff when receiving 429 responses
2. Cache results when possible to reduce API calls
3. Batch operations when supported
4. Contact support if you need higher limits

Example: Exponential Backoff

import time
import requests

def make_request_with_retry(url, headers, payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=payload, headers=headers)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
        time.sleep(retry_after)

    return response

Versioning

AiPrise uses URL-based versioning to ensure backward compatibility.

Current Version

The current API version is v1, indicated in the URL path:

https://api.aiprise.com/api/v1/

Version Policy

• Backward Compatibility: We maintain backward compatibility within major versions
• Breaking Changes: Introduced only in new major versions (v2, v3, etc.)
• Deprecation Notice: Minimum 90 days advance notice before deprecating features
• Version Support: Each major version supported for at least 12 months after next version release

What Constitutes a Breaking Change

Breaking changes include:

• Removing or renaming fields in responses
• Changing field data types
• Removing endpoints
• Changing authentication methods
• Modifying error response formats

Non-Breaking Changes

These may be introduced without version changes:

• Adding new optional request fields
• Adding new fields to responses
• Adding new endpoints
• Adding new HTTP methods to existing endpoints
• Changing the order of fields in responses (clients should not depend on order)

Deprecation Process

1. Announcement: Feature marked as deprecated in documentation
2. Deprecation Headers: Sunset and Deprecation headers added to responses
3. Migration Guide: Documentation provided for migration path
4. Grace Period: Minimum 90 days before removal
5. Removal: Feature removed in next major version

Example Deprecation Header:

Deprecation: true
Sunset: Wed, 31 Dec 2024 23:59:59 GMT
Link: <https://docs.aiprise.com/migration-v2>; rel="sunset"

SDKs & Libraries

AiPrise uses standard REST/HTTP conventions, making it compatible with any programming language. TODO(Rajat): Add URL here-->

Official SDKs

You can go through the SDK section of our documentation to find details and guides.

HTTP Client Examples

Python (using requests):

import requests

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key_here"
}

payload = {
    "template_id": "your-template-id",
    "user_data": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-01-15"
    }
}

response = requests.post(
    "https://api-sandbox.aiprise.com/api/v1/verify/run_user_verification",
    json=payload,
    headers=headers
)

result = response.json()
print(result)

JavaScript/Node.js (using fetch):

const response = await fetch(
  "https://api-sandbox.aiprise.com/api/v1/verify/run_user_verification",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "your_api_key_here",
    },
    body: JSON.stringify({
      template_id: "your-template-id",
      user_data: {
        first_name: "John",
        last_name: "Doe",
        date_of_birth: "1990-01-15",
      },
    }),
  }
);

const result = await response.json();
console.log(result);

cURL:

curl -X POST https://api-sandbox.aiprise.com/api/v1/verify/run_user_verification \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "template_id": "your-template-id",
    "user_data": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15"
    }
  }'

OpenAPI/Swagger Specifications

AiPrise provides OpenAPI 3.0 specifications for code generation:

• Verification API Spec: Available in the Dashboard or via API
  • Backoffice API Spec: Available for admin operations
    

Support & Resources

Documentation

• Main Documentation: https://docs.aiprise.com
  • API Reference: Complete endpoint reference with request/response examples (TODO(Rajat): add urls here)
    • Integration Guides: Step-by-step tutorials for common use cases
    • Changelog: Updates and version history

Developer Dashboard

Access your dashboard at https://dashboard.aiprise.com to:

• Generate and manage API keys
  • Create and configure templates
    • Build verification workflows
      • View verification history
        • Test integrations
          • Monitor API usage
            • Access analytics and reports
              

Support Channels

Technical Support:

• Email: [email protected]
  • Response Time: Within 24 hours for standard inquiries, faster for critical issues

Sales & Business Inquiries:

• Email: [email protected]

Webhook Security

AiPrise signs all webhook requests to ensure authenticity. Verify webhook signatures to prevent spoofing:

1. Each webhook includes an X-HMAC-SIGNATURE header
2. Use your webhook signing secret to verify the signature
3. Reject webhooks with invalid signatures

Example Verification (Python):

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature)

Service Level Agreement (SLA)

• API Uptime: 99.9% uptime guarantee
• Response Times:
  • Synchronous verifications: < 10 seconds (p95)
  • Webhook delivery: < 5 seconds after completion
  • API endpoint latency: < 500ms (p95)

Status Page

Monitor AiPrise service status and subscribe to incident notifications:

• Status Page: https://status.aiprise.com (if available)
• Subscribe to status updates via email or SMS

Best Practices

1. Test in Sandbox First: Always develop and test integrations in Sandbox before using Production
2. Handle Webhooks Asynchronously: Return 200 OK quickly, process webhook data in background jobs
3. Implement Retries: Handle transient errors with exponential backoff
4. Monitor Rate Limits: Track rate limit headers and adjust request patterns
5. Validate Input: Validate user data before sending to AiPrise to avoid validation errors
6. Store Session IDs: Keep track of verification_session_id for future reference and debugging
7. Use Idempotency: Always include client_reference_id to prevent duplicate verifications
8. Secure Your Webhooks: Verify webhook signatures to ensure authenticity

Next Steps

Now that you understand the basics, dive into specific topics:

• Core Concepts: Learn about templates, sessions, profiles, and file handling
• KYC (Users): Implement user identity verification
• KYB (Businesses): Implement business verification
• Callbacks & Events: Set up webhooks for real-time notifications
• Guides: Follow quickstarts and integration walkthroughs

Ready to start building? Head to the Guides section for end-to-end quickstarts.