Help CenterHow to get verified
uValid
Developer Program

UValid API Documentation

Integrate UValid Cloud Platform identity, business, and compliance verification services into your onboarding and risk workflows. All endpoints are secured with JWT bearer tokens issued via the admin console.

Authentication

Access to the client API layer is controlled through signed JWT tokens. Administrators can create and manage partners under Admin → API Users. Each token carries scoped permissions corresponding to the services granted to that client.

  • Authorization: Bearer <token> header is required for every request.
  • Tokens are versioned; regenerating a token invalidates all previous copies immediately.
  • Scopes align with service keys (for example identity:nin or business:cac-basic).

Environment Configuration

Make sure the following environment variables are configured before issuing tokens:

  • API_JWT_SECRET – required symmetric signing key.
  • API_JWT_ISSUER, API_JWT_AUDIENCE, API_JWT_EXPIRES_IN – optional overrides (default expiry: 90 days).
  • DIKRIPT_API_KEY – upstream verification provider key used across all services.

Identity Verification

POST
/client/identity/nin
identity:nin

Returns NIN profile information with biodata, portrait, and consent trail metadata.

Request body

{
  "nin": "string // 11 digit NIN"
}

Example payload

{
  "nin": "12345678901"
}
POST
/client/identity/bvn
identity:bvn

Retrieves BVN-linked identity attributes and status indicators.

Request body

{
  "bvn": "string // 11 digit BVN"
}

Example payload

{
  "bvn": "12345678901"
}
POST
/client/identity/bvn-nin
identity:bvn-nin

Confirms harmonisation between BVN and NIN registries with enrichment metadata.

Request body

{
  "bvn": "string // 11 digit BVN"
}

Example payload

{
  "bvn": "12345678901"
}

Phone Intelligence

POST
/client/phone/basic
phone:basic

Basic MSISDN verification with ownership and contact discovery.

Request body

{
  "phoneNo": "string // Nigerian MSISDN (+234 or 0 prefix)"
}

Example payload

{
  "phoneNo": "+2347012345678"
}
POST
/client/phone/advanced
phone:advanced

Advanced MSISDN intelligence covering SIM swap history and behavioural indicators.

Request body

{
  "phoneNo": "string // Nigerian MSISDN (+234 or 0 prefix)"
}

Example payload

{
  "phoneNo": "+2347012345678"
}

Business & KYB

POST
/client/business/cac-basic
business:cac-basic

Foundational Corporate Affairs Commission registration data.

Request body

{
  "regNumber": "string // CAC registration number (min 4 chars)"
}

Example payload

{
  "regNumber": "RC123456"
}
POST
/client/business/cac-advanced
business:cac-advanced

Expanded CAC filings, officers, and compliance flags.

Request body

{
  "regNumber": "string // CAC registration number (min 4 chars)"
}

Example payload

{
  "regNumber": "RC123456"
}
POST
/client/business/cac-premium
business:cac-premium

Premium CAC intelligence including beneficial ownership mapping.

Request body

{
  "regNumber": "string // CAC registration number (min 4 chars)"
}

Example payload

{
  "regNumber": "RC123456"
}
POST
/client/business/cac-by-name
business:cac-by-name

Discover candidate CAC matches via business name search.

Request body

{
  "businessName": "string // Registered or trade name (min 3 chars)"
}

Example payload

{
  "businessName": "Orbital Bank"
}

Compliance & Licensing

POST
/client/other/tin
other:tin

Validate FIRS Tax Identification Numbers and compliance status.

Request body

{
  "tin": "string // XXXXXXXX-XXXX format"
}

Example payload

{
  "tin": "01234567-0001"
}
POST
/client/other/frsc
other:frsc

Verify Federal Road Safety Corps driver licence records.

Request body

{
  "frsc": "string // Alphanumeric, 8+ characters"
}

Example payload

{
  "frsc": "ABC12345"
}

Standard Response Shape

{
  "success": true,
  "data": { ... },          // Provider payload
  "meta": {
    "fromCache": false,     // true if served from Firestore cache
    "timestamp": "2024-04-17T12:00:00.000Z"
  }
}

Validation errors return HTTP 400 with success: false. Authentication or scope violations return HTTP 401/403. Upstream issues respond with HTTP 500 and a descriptive message.

Postman Collection (Preview)

{
  "info": {
    "name": "UValid Verification APIs",
    "description": "Programmatic access to UValid Cloud Platform verification services. Authenticated with JWT tokens issued via the Admin Console.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://nxsggghpzjhpkprxgjln.supabase.co/functions/v1/uvalid"
    },
    {
      "key": "apiToken",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "Identity Verification",
      "item": [
        {
          "name": "NIN Lookup",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nin\": \"12345678901\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/identity/nin",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "identity",
                "nin"
              ]
            },
            "description": "Returns NIN profile information with biodata, portrait, and consent trail metadata.\nScope: identity:nin"
          }
        },
        {
          "name": "BVN Lookup",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"bvn\": \"12345678901\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/identity/bvn",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "identity",
                "bvn"
              ]
            },
            "description": "Retrieves BVN-linked identity attributes and status indicators.\nScope: identity:bvn"
          }
        },
        {
          "name": "BVN ↔ NIN Linkage",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"bvn\": \"12345678901\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/identity/bvn-nin",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "identity",
                "bvn-nin"
              ]
            },
            "description": "Confirms harmonisation between BVN and NIN registries with enrichment metadata.\nScope: identity:bvn-nin"
          }
        }
      ]
    },
    {
      "name": "Phone Intelligence",
      "item": [
        {
          "name": "Phone Basic",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phoneNo\": \"+2347012345678\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/phone/basic",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "phone",
                "basic"
              ]
            },
            "description": "Basic MSISDN verification with ownership and contact discovery.\nScope: phone:basic"
          }
        },
        {
          "name": "Phone Advanced",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phoneNo\": \"+2347012345678\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/phone/advanced",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "phone",
                "advanced"
              ]
            },
            "description": "Advanced MSISDN intelligence covering SIM swap history and behavioural indicators.\nScope: phone:advanced"
          }
        }
      ]
    },
    {
      "name": "Business & KYB",
      "item": [
        {
          "name": "CAC Basic",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"regNumber\": \"RC123456\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/business/cac-basic",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "business",
                "cac-basic"
              ]
            },
            "description": "Foundational Corporate Affairs Commission registration data.\nScope: business:cac-basic"
          }
        },
        {
          "name": "CAC Advanced",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"regNumber\": \"RC123456\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/business/cac-advanced",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "business",
                "cac-advanced"
              ]
            },
            "description": "Expanded CAC filings, officers, and compliance flags.\nScope: business:cac-advanced"
          }
        },
        {
          "name": "CAC Premium",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"regNumber\": \"RC123456\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/business/cac-premium",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "business",
                "cac-premium"
              ]
            },
            "description": "Premium CAC intelligence including beneficial ownership mapping.\nScope: business:cac-premium"
          }
        },
        {
          "name": "CAC Search by Name",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"businessName\": \"Orbital Bank\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/business/cac-by-name",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "business",
                "cac-by-name"
              ]
            },
            "description": "Discover candidate CAC matches via business name search.\nScope: business:cac-by-name"
          }
        }
      ]
    },
    {
      "name": "Compliance & Licensing",
      "item": [
        {
          "name": "TIN Verification",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"tin\": \"01234567-0001\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/other/tin",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "other",
                "tin"
              ]
            },
            "description": "Validate FIRS Tax Identification Numbers and compliance status.\nScope: other:tin"
          }
        },
        {
          "name": "FRSC Licence",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiToken}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"frsc\": \"ABC12345\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/client/other/frsc",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "client",
                "other",
                "frsc"
              ]
            },
            "description": "Verify Federal Road Safety Corps driver licence records.\nScope: other:frsc"
          }
        }
      ]
    }
  ]
}

Service Scopes Reference

Identity · NIN Lookup

Validate a National Identification Number and retrieve associated profile data.

identity:nin

Identity · BVN Lookup

Verify a Bank Verification Number and return linked identity attributes.

identity:bvn

Identity · BVN ↔ NIN Linkage

Confirm the linkage between BVN and NIN records including harmonised metadata.

identity:bvn-nin

Phone · Basic Lookup

Basic MSISDN lookups for ownership validation and contact discovery.

phone:basic

Phone · Advanced Insight

Advanced MSISDN analytics covering SIM history, activity signals, and risk posture.

phone:advanced

Business · CAC Basic

Corporate Affairs Commission lookup with foundational company registration data.

business:cac-basic

Business · CAC Advanced

Expanded CAC profile with filings, officers, and compliance flags.

business:cac-advanced

Business · CAC Premium

Premium CAC intelligence including beneficial ownership and historical insights.

business:cac-premium

Business · CAC Search by Name

Search CAC records by business name, returning candidate matches and metadata.

business:cac-by-name

Compliance · TIN Verification

Validate Tax Identification Numbers and retrieve tax entity details.

other:tin

Compliance · FRSC Licence

Verify Federal Road Safety Corps driver licence records.

other:frsc

Identity · PEP Screening

AI-powered Politically Exposed Person screening for Nigerian entities.

identity:pep-screening

Phone · NIN Lookup

Verify a phone number and retrieve associated NIN identity data.

phone:nin

Compliance · Passport Verification

Verify Nigerian international passport details.

other:passport

Business · CAC Business Validation

Advanced CAC VAS multi-action business validation including company lookup, TIN, certificates, affiliates, and compliance.

business:cac-business

Business · BN Registration

Submit a Business Name (sole proprietor) registration to CAC.

business:bn-business-name

Business · BN Partner

Register an additional partner / proprietor on an existing Business Name application.

business:bn-partner

Business · BN Pre-Reg Validation

Validate Business Name registration data and surface field-level errors before submission.

business:bn-validation

Business · BN Name Compliance

Check proposed Business Name uniqueness, similarity score, and compliance score.

business:bn-compliance

Business · BN Query Response

Respond to a query raised on a Business Name registration (e.g. re-upload signature / passport).

business:bn-query

Business · BN Certificate Download

Retrieve the registration certificate image URL for an approved Business Name.

business:bn-certificate

Business · BN Status Report

Download the status report for a Business Name registration transaction.

business:bn-status-report

Business · LLC Affiliates

Add a director / shareholder / secretary affiliate to an LLC registration.

business:llc-affiliates

Business · LLC Company

Submit the company details for a Limited Liability Company registration.

business:llc-company

Business · LLC Name Compliance

Check proposed LLC company name uniqueness, similarity score, and compliance score.

business:llc-compliance

Business · LLC Name Reservation

Reserve an approved company name for a Limited Liability Company.

business:llc-name-reservation

Business · LLC PSC

Register a Person with Significant Control (PSC) for an LLC.

business:llc-psc

Business · LLC Register

Submit the completed LLC application to CAC for registration.

business:llc-register

Business · LLC Shares

Define share capital and allot shares across LLC affiliates / shareholders.

business:llc-shares

Business · LLC Stamp Duty

Compute and pay stamp duty on an LLC share capital.

business:llc-stamp-duty

Business · LLC Status

Check the registration status of an LLC application.

business:llc-status