Identity Verification API

Identity Verification API - Integration Guide

Welcome to the Identity Verification API!
This service provides AI-powered identity verification using video selfies and ID photos with OpenAI Vision analysis.

Authentication

All API requests require authentication using an API key. Contact your integration team to obtain your unique API key.

API Key: Required for all requests. Pass as api_key parameter.

API Integration

Verification Interface Endpoint

GET /verif/
Serves the verification interface with partner theming

Required Parameters

Parameter Type Required Description
api_key string ✅ Yes Your unique API key for authentication
user_id or user_identifier string ✅ Yes Unique identifier for the user being verified

Optional Parameters

Parameter Type Required Description
user_email string ❌ No User's email address for record keeping
user_phone string ❌ No User's phone number for record keeping

Example Integration URL

https://your-domain.com/verif/?api_key=YOUR_API_KEY&user_identifier=user123&user_email=user@example.com

Verification Submission Endpoint

POST /verif/submit
Processes verification files and returns results

Request Format

Submit as multipart/form-data with the following fields:

Field Type Required Description
api_key string ✅ Yes Your API key
user_identifier string ✅ Yes User identifier
selfie_video file ✅ Yes Video file of user's selfie (max 50MB)
id_photo file ✅ Yes Image file of government ID
user_email string ❌ No User's email address
user_phone string ❌ No User's phone number

Response Format

{
  "success": true,
  "check_id": "uuid-session-id",
  "result": {
    "sessionId": "uuid-session-id",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "files": {
      "selfieVideo": {
        "url": "https://storage.azure.com/...",
        "fileName": "session_selfie_timestamp.mp4"
      },
      "idPhoto": {
        "url": "https://storage.azure.com/...",
        "fileName": "session_id_timestamp.jpg"
      }
    },
    "faceComparison": {
      "isIdentical": true,
      "confidence": 0.85,
      "similarityScore": 85,
      "method": "openai_vision"
    },
    "verificationAssessment": {
      "overallScore": 85,
      "verificationStatus": "verified",
      "confidenceLevel": "high",
      "summary": "Verification completed successfully"
    },
    "status": "verified"
  }
}

Webhook Setup

Webhook Notifications: Receive real-time verification results at your endpoint

Configuration

Configure your webhook URL in your partner settings. The system will send a POST request to your endpoint when verification is complete.

Webhook Payload Structure

{
  "check_id": "uuid-session-id",
  "user_identifier": "user123",
  "verification_result": {
    "sessionId": "uuid-session-id",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "status": "verified",
    "faceComparison": {
      "isIdentical": true,
      "confidence": 0.85,
      "similarityScore": 85
    },
    "verificationAssessment": {
      "overallScore": 85,
      "verificationStatus": "verified",
      "confidenceLevel": "high"
    }
  },
  "selfie_video_url": "https://storage.azure.com/...",
  "id_photo_url": "https://storage.azure.com/...",
  "completed_at": "2024-01-15T10:30:00.000Z"
}

Webhook Response Requirements

Status Code Description
200-299 Success - webhook received and processed
400+ Error - webhook will be marked as failed
Important: Your webhook endpoint must respond within 10 seconds or the request will timeout.

Webhook Security

Implementation Examples

Basic Integration Flow

// 1. Redirect user to verification interface
const verificationUrl = `https://your-domain.com/verif/?api_key=${API_KEY}&user_identifier=${userId}&user_email=${userEmail}`;
window.location.href = verificationUrl;

// 2. Handle webhook notification
app.post('/webhook/verification', (req, res) => {
  const { check_id, user_identifier, verification_result } = req.body;
  
  // Process verification result
  if (verification_result.status === 'verified') {
    // Mark user as verified in your system
    await markUserAsVerified(user_identifier);
    console.log(`User ${user_identifier} verified successfully`);
  } else {
    // Handle verification failure
    await handleVerificationFailure(user_identifier, verification_result);
    console.log(`User ${user_identifier} verification failed`);
  }
  
  // Respond with success
  res.status(200).json({ received: true });
});

Verification Status Handling

// Handle different verification outcomes
function processVerificationResult(result) {
  const { status, verificationAssessment } = result;
  
  switch (status) {
    case 'verified':
      // User passed verification
      if (verificationAssessment.confidenceLevel === 'high') {
        // Automatically approve
        approveUser(result.user_identifier);
      } else {
        // May require additional review
        flagForReview(result.user_identifier, 'medium_confidence');
      }
      break;
      
    case 'rejected':
      // User failed verification
      rejectUser(result.user_identifier, verificationAssessment.riskFactors);
      break;
      
    default:
      // Handle unexpected status
      flagForManualReview(result.user_identifier, 'unknown_status');
  }
}

Troubleshooting

Common Error Codes

Status Code Error Solution
400 API key is required Include api_key parameter in your request
400 User identifier is required Include user_id or user_identifier parameter
401 Invalid API key Verify your API key is correct and active
400 Both selfie video and ID photo are required Ensure both files are included in the submission
500 Verification processing failed Check file formats and sizes, retry if necessary

File Requirements

Best Practices

Integration Checklist

Before Going Live:

Support

For technical support or questions about integration:

Security Note: Never expose your API key in client-side code. Always handle API calls from your secure backend.