Home / Documentation / Verification API

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.

Get API Keys

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).

Base URLs
Production https://your-domain.example.com
Local Development http://localhost:8000

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

  1. Log in to your account and navigate to API Keys (/api/keys/).
  2. In the Create a new API key card, enter a label for your service (e.g. Production Backend).
  3. Click Generate Key.
  4. 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.

Example Request (cURL)
curl -X POST "https://your-domain.example.com/api/v1/verify/" \
  -H "Content-Type: application/json" \
  -d '{
    "uniface_id": "UID-ABCD-EFGH-JKLM"
  }'
Expected Responses
200 OK — Verified Success
{
  "valid": true,
  "status": "verified",
  "verified_at": "2026-09-18T20:30:00+00:00",
  "name": "Joseph Samwa"
}
404 Not Found — Invalid Error
{
  "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.

Example Request with API Key (cURL)
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"
  }'
Expected Responses
200 OK — Details Unlocked Success
{
  "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"
  }
}
402 Payment Required — Valid ID, But Details Locked No Key / Payment
{
  "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

200 OK

Verification confirmed or details unlocked successfully.

400 Bad Request

Missing uniface_id or record is currently pending/failed.

402 Payment Required

UnifaceID is valid, but full profile details require an API key or paid purchase.

404 Not Found

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.