UniFace Verification API
Integrate proof of human verification into your application. Verify unique UnifaceIDs, authenticate server requests with API keys, and securely retrieve verified profile details.
Overview & Base URL
The UniFace Verification API allows your backend systems to programmatically verify human identity authenticity using an individual's UnifaceID (e.g. UID-ABCD-EFGH-JKLM).
All API endpoints accept POST requests with either application/json or application/x-www-form-urlencoded payloads.
Managing API Keys
UniFace allows registered users to create and manage their own API keys directly within the web application. Keys are prefixed with uf_.
How to generate an API key
- Log in to your account and navigate to API Keys (/api/keys/).
- In the Create a new API key card, enter a label for your service (e.g. Production Backend).
- Click Generate Key.
- Copy your key immediately — the full key is only displayed once after creation; later only a masked version is shown.
Authentication Methods
Depending on the endpoint, authentication is handled in one of three ways:
| Endpoint | Requirement | Authentication Header |
|---|---|---|
| POST /api/v1/verify/ | Public (No Auth) | None required |
| POST /api/v1/verify/details/ | Protected (Full Details) |
Header: X-API-Key: uf_...
Or: Authorization: Bearer uf_...
|
1. Verify an UnifaceID
POST /api/v1/verify/Confirms whether an UnifaceID belongs to an active, verified human record. Returns basic status and the verified person's full name.
curl -X POST "https://your-domain.example.com/api/v1/verify/" \
-H "Content-Type: application/json" \
-d '{
"uniface_id": "UID-ABCD-EFGH-JKLM"
}'
{
"valid": true,
"status": "verified",
"verified_at": "2026-09-18T20:30:00+00:00",
"name": "Joseph Samwa"
}
{
"valid": false,
"status": "invalid"
}
2. Verify & Retrieve Details
POST /api/v1/verify/details/Returns full identity details (email, phone, country, gender) for a verified UnifaceID. Requires a valid API key or a successful payment reference.
curl -X POST "https://your-domain.example.com/api/v1/verify/details/" \
-H "Content-Type: application/json" \
-H "X-API-Key: uf_YOUR_API_KEY_HERE" \
-d '{
"uniface_id": "UID-ABCD-EFGH-JKLM"
}'
{
"valid": true,
"status": "verified",
"details_unlocked": true,
"verification": {
"uniface_id": "UID-ABCD-EFGH-JKLM",
"verified_at": "2026-09-18T20:30:00+00:00",
"status": "VERIFIED"
},
"user": {
"full_name": "Joseph Samwa",
"email": "[email protected]",
"phone_country_code": "+254",
"phone_number": "712345678",
"declared_country": "KE",
"gender": "male"
}
}
{
"valid": true,
"status": "verified",
"name": "Joseph Samwa",
"details_unlocked": false,
"error": "Successful payment is required to access full details."
}
Field Reference
| Field | Type | Description |
|---|---|---|
| uniface_id | string | Unique verification identifier (e.g. UID-ABCD-EFGH-JKLM). |
| valid | boolean | true when identity is verified and active. |
| status | string | Status code: verified, pending, failed, expired, invalid. |
| verified_at | ISO 8601 string | UTC timestamp when verification was completed, or null. |
| name | string | User's verified full name when record is valid. |
| details_unlocked | boolean | Whether full user metadata dictionary is included in the response. |
| user.email | string | Verified email address of the individual. |
| user.phone_number | string | Phone number digits with country dialing code prefix. |
| user.declared_country | string | Two-letter ISO 3166-1 country code (e.g. KE). |
HTTP Status Codes
Verification confirmed or details unlocked successfully.
Missing uniface_id or record is currently pending/failed.
UnifaceID is valid, but full profile details require an API key or paid purchase.
The requested UnifaceID does not match any record in the system.
Integration Code Examples
import os
import requests
API_BASE = "https://your-domain.example.com"
API_KEY = os.environ.get("UNIFACE_API_KEY", "uf_your_api_key_here")
# 1. Quick verification check (Public)
def is_verified(uniface_id: str) -> bool:
resp = requests.post(f"{API_BASE}/api/v1/verify/", json={"uniface_id": uniface_id})
if resp.status_code == 200:
data = resp.json()
print(f"Verified user: {data['name']}")
return data.get("valid", False)
return False
# 2. Unlock full profile details (Protected)
def get_user_details(uniface_id: str) -> dict:
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
resp = requests.post(
f"{API_BASE}/api/v1/verify/details/",
json={"uniface_id": uniface_id},
headers=headers,
)
if resp.status_code == 200:
return resp.json().get("user", {})
return {}
# Run
if __name__ == "__main__":
test_id = "UID-ABCD-EFGH-JKLM"
if is_verified(test_id):
print(get_user_details(test_id))
Security & Privacy Guidelines
-
Backend Only: Always call
/api/v1/verify/details/from secure servers. Never expose your API keys in frontend JavaScript, mobile binaries, or public Git repos. - Instant Revocation: If an API key is accidentally exposed, immediately revoke it in the API Keys Dashboard and generate a replacement.
- Liveness vs KYC: UniFace Verify confirms human liveness and platform registration. It does not replace national legal identity documentation or government KYC registries.