Skip to content

KYC / KYB API

Documentation status

Last verified: 26 Sep 2026. Endpoint inventory: generated endpoint map. Status labels: status vocabulary. Confirm deployed bases with MasteryHive.

HTTP-first FastAPI service. Prefer OpenAPI reference or live /docs for schemas.

Base URL

Deployed base URLs are environment-specific (confirm with MasteryHive). Local development defaults, if used, are agreed separately with your account team.

Endpoint map

Canonical path list (generated from OpenAPI): KYC / KYB endpoint map.

Grouped view (same paths):

Tag Paths
Monitoring GET /health
ID POST /prembly_id_check, POST /id_check/all
Business POST /prembly_business_check
Address POST /prembly_address_check
Documents POST /prembly_doc_check, POST /doc_extract, POST /doc_check/all
Biodata POST /biodata_check
Report / risk POST /generate_report, POST /calculate_customer_risk_profile
Screening POST /find_person, POST /open_sanction_finder, POST /pep_and_sanction_checker, POST /adverse_media_screener
Biometrics POST /liveliness_check, POST /face_comparison, POST /face_comparison/id_images, POST /edt/liveliness_check

Integration tips

  1. GET /health first.
  2. Common onboarding chain: ID/doc → liveliness/face → screening → risk/report. Some routes read results stored by earlier calls for the same userId: /biodata_check needs /prembly_doc_check and /doc_extract (or /doc_check/all) first, and /face_comparison and /edt/liveliness_check need a BVN lookup (verification_type: "bvn") and, for /face_comparison, a passed /liveliness_check.
  3. Every route takes a JSON body; there are no multipart uploads. Documents and videos are passed as Cloud Storage HTTPS URLs (https://storage.googleapis.com/<bucket>/<object>; gs:// URIs are not accepted), and /face_comparison/id_images takes optional base64 images in JSON. Copy field names from the OpenAPI schema; do not guess.
  4. Keep vendor and cloud credentials server-side.
  5. A 200 response does not mean the check passed. Most routes return 200 with a failure body when a check fails or a provider is unavailable. See Reading responses.

Reading responses: HTTP 200 is not a pass

Non-200 statuses: 422 for request validation errors (every route). Some routes also return 400 (for example /find_person when screening data is unavailable, /face_comparison/id_images, unreadable files on /liveliness_check, and network errors on the sanctions routes) or 500 (/calculate_customer_risk_profile errors, liveness model errors, and /edt/liveliness_check failures).

For everything else, read the decision field:

Route Decide on Passed when Watch out for
/prembly_id_check check_result.status true db_update reports storage, not the outcome
/id_check/all status true Read reason on failure
/prembly_doc_check check_result.status true Per-field match_status explains mismatches
/doc_extract status and extracted_id_data status: true and data present extracted_id_data: null means nothing was extracted
/doc_check/all status true One failing branch returns the whole failure body
/biodata_check status true Needs the document checks for the same userId first
/prembly_business_check status true Read detail
/prembly_address_check status and data.verification_status status: true and a completed verification A pending verification can be returned; re-check later rather than treating it as final
/open_sanction_finder, /pep_and_sanction_checker is_pep, is_sanctioned both false means no hit A provider error can show as a hit (true), and a partial provider failure can hide a hit. Treat unexpected results as needing review
/adverse_media_screener status and the result lists — A provider failure currently looks the same as a clean result (status: false, empty lists). Do not treat empty results as clearance on their own
/liveliness_check check_result passed —
/face_comparison, /face_comparison/id_images comparison_results[].same at least one same: true status: true does not mean the faces matched; it means a comparison ran
/edt/liveliness_check liveliness_check_data.check_result and comparison_results[].same liveness passed and a same: true final_decision: true does not mean a match; it means a comparison ran
/generate_report riskLevel a real risk level riskLevel: "Unknown" with ai_response: "Error generating report" means the report failed
/health — — Always 200 while the service is running

goAML

An offline library generates goAML-format XML from Excel/JSON. It is PARTIAL: not a public HTTP product surface and it does not submit to the NFIU. Ask MasteryHive if your programme needs it.

Auth

See Auth and tenancy. Production authentication and exposure are environment-specific agreements with MasteryHive; the OpenAPI export documents shapes, not a universal public anonymous contract.