Verification Workflow API
API endpoints for KYC verification processing using AWS Rekognition (face comparison) and AWS Textract (OCR).
Base URL: /verification
Endpoints Summary
| Method | Endpoint | Description |
|---|---|---|
| POST | /verification/process/:jobId | Trigger verification |
| GET | /verification/results/:jobId | Get verification results |
| GET | /verification/status/:jobId | Get current status |
| POST | /verification/test-face-comparison | Test face matching |
| POST | /verification/test-ocr | Test OCR extraction |
Process Verification
POST /verification/process/:jobId
Triggers the full verification workflow for a KYC job.
Prerequisites:
- Job must exist
- User must have uploaded ID front and selfie images
- ID back image is optional
Returns:
| Field | Description |
|---|---|
jobId | Job UUID |
status | COMPLETED, REJECTED, or FAILED |
currentStage | Current workflow stage |
progressPercentage | 0-100 completion |
ocrResult | Extracted ID data |
faceComparisonResult | Face match result |
decision | approved, rejected, or manual_review |
Get Verification Results
GET /verification/results/:jobId
Returns: Complete verification results including:
| Field | Description |
|---|---|
jobId | Job UUID |
status | Job status |
stageProgress | Progress of each stage |
rejectionReason | Reason if rejected |
userInfo | User profile and images |
Get Verification Status
GET /verification/status/:jobId
Returns:
| Field | Description |
|---|---|
currentStatus | PENDING, PROCESSING, COMPLETED, REJECTED |
currentStage | Active workflow stage |
progressPercentage | Completion percentage |
stageProgress | Status of each stage |
estimatedTimeRemaining | Estimated time to complete |
Test Face Comparison
POST /verification/test-face-comparison
Tests face comparison without creating a job.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
sourceImage | string | Yes | ID document image URL |
targetImage | string | Yes | Selfie image URL |
similarityThreshold | number | No | Match threshold (default: 80) |
Returns:
| Field | Description |
|---|---|
isMatch | true/false based on threshold |
similarity | Similarity percentage (0-100) |
confidence | AWS confidence score |
faceDetails | Bounding box and quality metrics |
decision | approved/rejected/manual_review |
Test OCR Extraction
POST /verification/test-ocr
Tests OCR extraction from a document image.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | string | Yes | Document image URL |
Returns:
| Field | Description |
|---|---|
personalInfo | Extracted name, ID, DOB, sex |
confidence | Extraction confidence (0-100) |
validation | Completeness and issues |
extractedFields | List of fields found |
Verification Stages
| Stage | Description | Duration |
|---|---|---|
submitted | Documents uploaded, awaiting processing | - |
ocr_processing | Extracting data from ID (AWS Textract) | ~3 min |
face_verification | Comparing selfie to ID (AWS Rekognition) | ~2 min |
final_review | Automated/manual review | ~1 min |
completed | Verification successful | - |
rejected | Verification failed | - |
Decision Types
| Decision | Description |
|---|---|
approved | Verification successful, user verified |
rejected | Verification failed, reason provided |
manual_review | Requires human review |
OCR Extracted Fields
| Field | Description |
|---|---|
firstName | First name from ID |
lastName | Last name from ID |
idNumber | Government ID number |
dateOfBirth | Date of birth (YYYY-MM-DD) |
sex | MALE or FEMALE |
nationality | Nationality |
expiryDate | ID expiry date |
Face Comparison Thresholds
| Threshold | Description |
|---|---|
| ≥80% | Match - approved |
| 60-79% | Uncertain - manual review |
| <60% | No match - rejected |
Error Responses
| Status | Error | Description |
|---|---|---|
| 404 | Job not found | Invalid job ID |
| 404 | KYC user data not found | User not found |
| 400 | Required images not found | Missing ID front or selfie |
| 500 | Face comparison failed | AWS Rekognition error |
| 500 | OCR extraction failed | AWS Textract error |