Prompt
identity verification API with liveness detection
Latest observation
Oct 29, 2026
OpenAI APIWeb search: off
Here’s a practical blueprint for an identity verification API with liveness detection.
Core flow
-
Create verification session
- Client requests a new session.
- API returns a
session_idand upload instructions.
-
Capture identity documents
- User submits front/back of ID or passport.
- API runs document validation and OCR.
-
Perform liveness detection
- User completes a selfie liveness check:
- passive liveness: blink / face movement / texture analysis
- active liveness: turn head, smile, read digits, follow a dot
- User completes a selfie liveness check:
-
Face match
- Compare selfie to ID photo.
- Return match score and decision.
-
Return decision
approved,rejected, orreview_required
Suggested API endpoints
1) Create session
POST /v1/verifications
Request
{
"user_id": "user_123",
"workflow": "id_plus_selfie_liveness",
"callback_url": "https://example.com/webhook"
}
Response
{
"verification_id": "ver_abc123",
"status": "pending",
"upload_urls": {
"document_front": "https://...",
"document_back": "https://...",
"selfie_video": "https://..."
}
}
2) Submit document
POST /v1/verifications/{verification_id}/document
Multipart form-data
file: image/PDFside:frontorback
Response
{
"status": "received",
"document_checks": {
"authenticity": "pending",
"ocr": "pending"
}
}
3) Start liveness challenge
POST /v1/verifications/{verification_id}/liveness/start
Response
{
"challenge_type": "active",
"instructions": [
"Turn your head left",
"Turn your head right",
"Smile"
],
"challenge_token": "lv_123"
}
4) Upload liveness video
POST /v1/verifications/{verification_id}/liveness/submit
Multipart form-data
video: liveness videochallenge_token: token from start endpoint
Response
{
"status": "processing"
}
5) Get result
GET /v1/verifications/{verification_id}
Response
{
"verification_id": "ver_abc123",
"status": "approved",
"results": {
"document": {
"authenticity": "pass",
"ocr_match": "pass"
},
"liveness": {
"result": "pass",
"score": 0.97
},
"face_match": {
"score": 0.94,
"threshold": 0.85
}
}
}
Important liveness detection options
Passive liveness
- No user action required
- Pros: better UX
- Cons: can be easier to spoof with advanced attacks
Active liveness
- User performs actions
- Pros: stronger anti-spoofing
- Cons: slightly more friction
Best practice
Use both:
- passive liveness as default
- fallback to active challenge if risk is high
Recommended decision model
Combine signals:
- document authenticity
- OCR consistency
- liveness score
- face similarity
- device/IP risk
- velocity/fraud history
Example:
- Approve if:
- document pass
- liveness ≥ 0.90
- face match ≥ 0.85
- Manual review if scores are borderline
- Reject if spoofing is detected
Security considerations
- Encrypt uploads at rest and in transit
- Use signed upload URLs
- Expire challenge tokens quickly
- Rate limit session creation and retries
- Store minimal biometric data
- Support audit logs and consent capture
- Comply with privacy laws:
- GDPR
- CCPA
- biometric data regulations in relevant jurisdictions
Recommended tech stack
- Backend: Node.js / Python / Go
- Storage: S3-compatible object store
- Queue: SQS / RabbitMQ / Kafka
- ML services: face detection, anti-spoofing, OCR
- Webhook worker: async result delivery
If you want to build it fast
You can integrate third-party providers such as:
- Onfido
- Jumio
- Veriff
- Persona
- Smile Identity
They already provide document verification + liveness APIs.
If you want, I can also provide:
- a complete OpenAPI spec
- a Node.js / Python implementation
- a database schema
- a liveness challenge design
- a webhook event model
If you'd like, I can draft the full API spec next.