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¶
GET /healthfirst.- Common onboarding chain: ID/doc → liveliness/face → screening → risk/report. Some routes read results stored by earlier calls for the same
userId:/biodata_checkneeds/prembly_doc_checkand/doc_extract(or/doc_check/all) first, and/face_comparisonand/edt/liveliness_checkneed a BVN lookup (verification_type: "bvn") and, for/face_comparison, a passed/liveliness_check. - 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_imagestakes optional base64 images in JSON. Copy field names from the OpenAPI schema; do not guess. - Keep vendor and cloud credentials server-side.
- A
200response does not mean the check passed. Most routes return200with 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.