Skip to main content
Hyparrow’s KYC endpoints proxy identity verification requests to Zeeh and Interswitch Verify, plus a NUBAN account lookup service. Each call is billed against your KYC balance or active plan quota.

​
Billing model

KYC calls are prepaid. You either subscribe to a monthly plan (which grants a quota of calls per endpoint type) or maintain a top-up balance that is debited per call.
  • If you have an active plan and the call falls within its quota, the call is free against your balance.
  • If your quota is exhausted or you have no active plan, the call is deducted from your balance.
  • Requests that exceed both quota and balance return 402 Payment Required.

​
Manage billing

​
Check your balance

GET /api/v1/kyc/balance
cURL
curl --request GET \
  --url https://api.hyparrow.com/api/v1/kyc/balance \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret"
Response
{
  "success": true,
  "data": {
    "balance": 4750.00
  }
}

​
List available plans

GET /api/v1/kyc/plans
cURL
curl --request GET \
  --url https://api.hyparrow.com/api/v1/kyc/plans \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret"

​
Subscribe to a plan

POST /api/v1/kyc/subscribe
​
planId
string
required
UUID of the plan to subscribe to. Retrieve plan IDs from GET /api/v1/kyc/plans.
cURL
curl --request POST \
  --url https://api.hyparrow.com/api/v1/kyc/subscribe \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --data '{ "planId": "plan-uuid-..." }'
Subscribing to a plan deducts the plan cost from your balance. Ensure sufficient balance before calling this endpoint.

​
Zeeh verification

Zeeh endpoints perform identity checks against Nigerian civil registries.
POST /api/v1/kyc/zee/bvn/basicReturns name, date of birth, and phone number associated with the BVN.
cURL
curl --request POST \
  --url https://api.hyparrow.com/api/v1/kyc/zee/bvn/basic \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --data '{ "bvn": "22200000001" }'
POST /api/v1/kyc/zee/bvn/advancedReturns the full BVN profile including residential address and enrollment bank.
cURL
curl --request POST \
  --url https://api.hyparrow.com/api/v1/kyc/zee/bvn/advanced \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --data '{ "bvn": "22200000001" }'
POST /api/v1/kyc/zee/ninLooks up the National Identification Number.
cURL
curl --request POST \
  --url https://api.hyparrow.com/api/v1/kyc/zee/nin \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --data '{ "nin": "12345678901" }'
POST /api/v1/kyc/zee/nin/with-faceLooks up the NIN and compares the registered photo against a supplied image URL.
Request body
{
  "nin": "12345678901",
  "imageUrl": "https://example.com/photo.jpg"
}
POST /api/v1/kyc/zee/voters-cardVerifies a Voter Identification Number (VIN).
Request body
{
  "vin": "91A2B3C4D5E6F7G8H9"
}
POST /api/v1/kyc/zee/phone/basicReturns the name and network associated with a Nigerian phone number.
Request body
{
  "phoneNumber": "+2348012345678"
}
POST /api/v1/kyc/zee/phone/advancedExtended phone lookup including SIM registration details.
Request body
{
  "phoneNumber": "+2348012345678"
}
POST /api/v1/kyc/zee/cac/basicBasic Corporate Affairs Commission lookup by RC number.
Request body
{
  "rcNumber": "RC123456",
  "companyName": "Acme Nigeria Ltd",
  "companyType": "RC"
}
POST /api/v1/kyc/zee/cac/advancedExtended CAC lookup including directors and registered address.
Request body
{
  "rcNumber": "RC123456",
  "companyName": "Acme Nigeria Ltd",
  "companyType": "RC"
}

​
Interswitch Verify

Interswitch Verify endpoints cover a broader set of identity documents and financial checks.
POST /api/v1/kyc/switch/ninReturns EXACT_MATCH or NO_MATCH for the supplied name against the NIN record.
Request body
{
  "nin": "12345678901",
  "firstName": "Jane",
  "lastName": "Doe"
}
POST /api/v1/kyc/switch/bvn/fullReturns the complete BVN profile.
Request body
{
  "bvn": "22200000001"
}
POST /api/v1/kyc/switch/bvn/boolean-matchReturns a name-match result for the BVN without exposing the full profile.
Request body
{
  "bvn": "22200000001",
  "firstName": "Jane",
  "lastName": "Doe"
}
POST /api/v1/kyc/switch/tinVerifies a Tax Identification Number.
Request body
{
  "tin": "12345678-0001"
}
POST /api/v1/kyc/switch/drivers-licenseVerifies a Nigerian driver’s license number.
Request body
{
  "licenseNumber": "AAA00000AA00"
}
POST /api/v1/kyc/switch/passportVerifies a Nigerian international passport.
Request body
{
  "passportNumber": "A00000000",
  "lastName": "Doe",
  "dob": "1990-04-15"
}
POST /api/v1/kyc/switch/cacSearches the CAC database by company name.
Request body
{
  "companyName": "Acme Nigeria"
}
POST /api/v1/kyc/switch/credit-historyRetrieves credit bureau history for the supplied BVN.
Request body
{
  "bvn": "22200000001"
}
POST /api/v1/kyc/switch/aml/domesticScreens a full name against Nigerian sanctions and watchlists.
Request body
{
  "fullName": "Jane Doe"
}
POST /api/v1/kyc/switch/aml/globalScreens a query against international sanctions databases.
Request body
{
  "type": "individual",
  "query": "Jane Doe"
}
POST /api/v1/kyc/switch/face-comparisonCompares two face images and returns a similarity score.
Request body
{
  "image1": "https://example.com/face1.jpg",
  "image2": "https://example.com/face2.jpg"
}

​
NUBAN account lookup

Resolve a bank account number to an account name. Useful for validating recipient accounts before transfers.
POST /api/v1/kyc/nuban/lookupAttempts to identify the bank and resolve the account name without specifying a bank.
cURL
curl --request POST \
  --url https://api.hyparrow.com/api/v1/kyc/nuban/lookup \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --data '{ "accountNumber": "0123456789" }'
POST /api/v1/kyc/nuban/lookup-with-bankResolves the account name at a specific bank.
Request body
{
  "accountNumber": "0123456789",
  "bankCode": "035"
}
POST /api/v1/kyc/nuban/guess-banksReturns a list of banks that are likely to hold the given account number, based on NUBAN routing rules.
Request body
{
  "accountNumber": "0123456789"
}

​
Standard response shape

All KYC endpoints return the same envelope: 
{
  "success": true,
  "data": {
    "..."
  }
}
On verification failure (e.g. no matching record), the provider response is forwarded inside data. On billing failure, the API returns 402 with an error string.

​
Call history

GET /api/v1/kyc/call-history Returns a paginated log of every verification call made by your account, including provider, endpoint, status, and the amount billed.
cURL
curl --request GET \
  --url "https://api.hyparrow.com/api/v1/kyc/call-history?page=1&limit=20" \
  --header "x-api-key: your_api_key" \
  --header "x-api-secret: your_api_secret"