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://uniface.world

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://uniface.world/api/v1/verify/" \
  -H "Content-Type: application/json" \
  -d '{
    "uniface_id": "UID-ABCD-EFGH-JKLM"
  }'
Expected Responses
200 OK — Active Success
{
  "valid": true,
  "is_active": true,
  "status": "verified",
  "verified_at": "2026-09-18T20:30:00+00:00",
  "expires_at": "2027-09-18T20:30:00+00:00",
  "name": "John Doe"
}
400 — Expired Expired
{
  "valid": false,
  "is_active": false,
  "status": "expired",
  "verified_at": "2025-09-18T20:30:00+00:00",
  "expires_at": "2026-09-18T20:30:00+00:00",
  "name": "John Doe"
}
404 Not Found Invalid
{
  "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://uniface.world/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 (Active) Success
{
  "valid": true,
  "is_active": true,
  "status": "verified",
  "details_unlocked": true,
  "verification": {
    "uniface_id": "UID-ABCD-EFGH-JKLM",
    "verified_at": "2026-09-18T20:30:00+00:00",
    "expires_at": "2027-09-18T20:30:00+00:00",
    "status": "VERIFIED",
    "is_active": true
  },
  "user": {
    "full_name": "John Doe",
    "email": "[email protected]",
    "phone_country_code": "+254",
    "phone_number": "712345678",
    "declared_country": "KE",
    "gender": "male"
  }
}
400 Bad Request — Expired (Details Unlocked) Expired
{
  "valid": false,
  "is_active": false,
  "status": "expired",
  "details_unlocked": true,
  "verification": {
    "uniface_id": "UID-ABCD-EFGH-JKLM",
    "verified_at": "2025-09-18T20:30:00+00:00",
    "expires_at": "2026-09-18T20:30:00+00:00",
    "status": "EXPIRED",
    "is_active": false
  },
  "user": {
    "full_name": "John Doe",
    "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,
  "is_active": true,
  "status": "verified",
  "name": "John Doe",
  "expires_at": "2027-09-18T20:30:00+00:00",
  "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.
is_active boolean true when the UnifaceID is active and within its validity duration; false if expired or unverified.
status string Status code: verified, pending, failed, expired, invalid.
verified_at ISO 8601 string UTC timestamp when verification was completed, or null.
expires_at ISO 8601 string UTC timestamp when the UnifaceID expires, or null for lifetime access.
name string User's verified full name when record is valid.
details_unlocked boolean Whether full user metadata dictionary is included in the response.
verification.is_active boolean Whether the credential is currently active and unexpired.
verification.expires_at ISO 8601 string Expiration timestamp of the specific verification credential.
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://uniface.world"
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.