Identity API Reference
Complete reference for the AfriRoute Identity API. All endpoints are rooted at the production base URL and authenticated with a bearer token.
🌐 Base URL & Authentication
| Base URL | https://api.afriroute.ai |
| Sandbox | https://sandbox.api.afriroute.ai |
| Auth header | Authorization: Bearer $AFRIROUTE_API_KEY |
| Content type | application/json |
curl https://api.afriroute.ai/api/v1/identity/verification/ver_abc123xyz \
-H "Authorization: Bearer $AFRIROUTE_API_KEY"
📡 Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/identity/verify-id | Full ID verification (OCR + authenticity + optional face/liveness) |
POST | /v1/identity/scan-document | OCR data extraction only |
POST | /v1/identity/face-match | Compare two faces |
POST | /v1/identity/liveness | Passive or active liveness check |
POST | /v1/identity/risk-score | Compute a fraud risk score |
POST | /v1/identity/phone/send-otp | Send a phone-verification OTP |
POST | /v1/identity/phone/verify-otp | Verify a phone OTP |
GET | /v1/identity/verification/:id | Retrieve a verification result |
GET | /v1/identity/audit/:id | Retrieve a verification audit log |
Per-endpoint parameters are documented on each feature page; this reference summarizes shared objects and conventions.
🧩 Shared Objects
risk_assessment
| Field | Type | Description |
|---|---|---|
risk_score | integer | 0–100 composite risk |
risk_level | string | low, medium, high, very_high |
flags | array | Machine-readable risk flags |
face_match
| Field | Type | Description |
|---|---|---|
match | boolean | Whether the faces matched |
confidence | number | Match confidence, 0–100 |
similarity_score | number | Raw similarity, 0–1 |
liveness
| Field | Type | Description |
|---|---|---|
passed | boolean | Whether the subject is live |
confidence | number | Liveness confidence, 0–100 |
method | string | passive or active |
🔁 Get Verification
GET /v1/identity/verification/:verification_id
{
"verification_id": "ver_abc123xyz",
"status": "verified",
"checks_performed": ["document_verification", "face_match", "liveness_detection"],
"results": {
"document_authentic": true,
"face_match": true,
"liveness_passed": true,
"overall_risk": "low"
},
"created_at": "2026-05-10T14:30:00Z",
"completed_at": "2026-05-10T14:30:45Z"
}
📊 Status Values
| Status | Meaning |
|---|---|
verified | All requested checks passed |
pending | Still processing or awaiting manual review |
rejected | One or more checks failed |
expired | Document past its expiry date |
⚡ Rate Limits
| Plan | Identity requests / min |
|---|---|
| Free | 10 |
| Starter | 60 |
| Growth | 300 |
| Enterprise | Custom |
Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are returned on every response. See retry logic for backoff guidance.
⚠️ Error Format
{
"success": false,
"error": {
"code": "IMAGE_QUALITY_LOW",
"message": "The document image is too blurry to process",
"request_id": "req_xyz789",
"timestamp": "2026-05-10T14:30:00Z"
}
}
Common identity error codes: INVALID_DOCUMENT_TYPE, IMAGE_QUALITY_LOW, NO_FACE_DETECTED, FACE_MISMATCH, LIVENESS_FAILED, OTP_EXPIRED, REGISTRY_UNAVAILABLE. The full catalog lives in the error code reference.
📚 Related Resources
- Identity Overview
- ID Verification · Document Scanning
- Face Match · Liveness
- Phone Verification · Risk Scoring
- Webhooks Overview
Last Updated: May 2026 | Need help? [email protected]