Skip to main content

​
Overview

TXCloud’s verification flow is designed to be flexible, supporting both synchronous (instant) and asynchronous (session-based) verification patterns.

​
Verification Methods

Instant Verification

Single API call with all images. Best for server-side integrations.

Session-Based

Multi-step upload flow. Best for mobile apps and web frontends.

​
Instant Verification Flow

Use this when you have all documents ready to submit at once: 
const verification = await txcloud.identity.verify({
  document_front: documentFrontBase64,
  document_back: documentBackBase64,  // optional
  selfie: selfieBase64,
  country: 'MA',
  document_type: 'national_id',
  checks: ['ocr', 'face_match', 'liveness', 'fraud']
});

​
Session-Based Flow

Use this for mobile apps where users capture documents step-by-step:

​
Step 1: Create Session

const session = await txcloud.identity.sessions.create({
  country: 'MA',
  document_type: 'national_id',
  checks: ['ocr', 'face_match', 'liveness'],
  webhook_url: 'https://yourapp.com/webhooks'
});

// Returns session_id and upload URLs
console.log(session.id); // 'sess_a1b2c3d4'

​
Step 2: Upload Documents

// Upload document front
await txcloud.identity.sessions.uploadDocument(session.id, {
  type: 'document_front',
  image: documentFrontBase64
});

// Upload document back (if required)
await txcloud.identity.sessions.uploadDocument(session.id, {
  type: 'document_back',
  image: documentBackBase64
});

// Upload selfie
await txcloud.identity.sessions.uploadDocument(session.id, {
  type: 'selfie',
  image: selfieBase64
});

​
Step 3: Complete Session

const verification = await txcloud.identity.sessions.complete(session.id);

// For async processing, listen for webhook
// or poll the verification status

​
Verification Checks

Each verification can include multiple checks:
CheckDescriptionTime
ocrExtract text from document~1s
face_matchCompare selfie to document photo~1s
livenessDetect if selfie is from live person~1s
fraudCheck for document tampering~2s
data_validationValidate extracted data formats~0.5s
age_verificationVerify user meets minimum age~0.5s
Only include the checks you need — fewer checks = faster processing.

​
Verification Statuses

StatusDescriptionFinal?
pendingProcessing in progressNo
verifiedAll checks passedYes
failedOne or more checks failedYes
expiredSession expired before completionYes
cancelledVerification was cancelledYes
manual_reviewRequires human reviewNo

​
Handling Results

const verification = await txcloud.identity.verifications.get(verificationId);

switch (verification.status) {
  case 'verified':
    // ✅ User verified - proceed with onboarding
    await onboardUser(verification.extracted_data);
    break;
    
  case 'failed':
    // ❌ Verification failed - check reasons
    const failures = verification.checks
      .filter(c => c.status === 'failed');
    await handleFailure(failures);
    break;
    
  case 'manual_review':
    // 👀 Needs human review
    await queueForReview(verification.id);
    break;
}

​
Best Practices

Check image quality client-side:
  • Minimum resolution: 1280x720
  • File size: Under 10MB
  • Format: JPEG or PNG
  • No blur or glare
Don’t poll — use webhooks for real-time updates on session-based verification.
Implement handlers for every possible status, including edge cases like expired.
Always store the verification ID for future reference and audit trails.

​
Next Steps

Identity API Reference

Explore all Identity endpoints

Fraud Detection Guide

Add fraud detection to your flow