POST /v1/verifications
Create a verification of any supported type and receive its identifier and status.
Resources
Build verification into your product
The Advanced API exposes every MasterID check behind one authenticated endpoint, with webhooks for results and a consistent response shape across check types.
EXAMPLE REQUEST
POST /v1/verifications
Authorization: Bearer <api_key>
Content-Type: application/json
{
"type": "id",
"reference": "onboarding-8412",
"subject": {
"id_number": "CM00000000000000",
"first_name": "Amina",
"last_name": "Nakato",
"date_of_birth": "1994-04-02"
},
"callback_url": "https://your-app.example/webhooks/masterid"
}Overview
One endpoint, every check
Submit a check, receive an immediate acknowledgement, then either poll or take the webhook when the result is ready.
- 01
Authenticate
Every request carries a bearer API key issued to your organisation. Keys are scoped per environment.
- 02
Submit a verification
POST the check type, your own reference and the subject attributes required for that check.
- 03
Receive the result
Take the webhook at your callback URL, or fetch the verification by its identifier.
- 04
Store the record
Persist the verification identifier so the check can be evidenced during an audit later.
Reference
What the API covers
Each check type accepts the attributes described on its own page and returns the same envelope.
- ID, Business, AML and CRB check types
- Product-level checks: NIN, TIN, bank account, KCCA licence, email, phone
- Idempotent submissions via your own reference
- Signed webhooks with retry on failure
- Sandbox environment with test subjects
- Consistent error codes and human-readable reasons
Access
API credentials are issued after your organisation is onboarded and the checks you need are agreed. Sandbox keys are available first so you can integrate before going live.
The full endpoint reference, response schemas and webhook signatures are shared with your developers when API access is provisioned.
Endpoints
The shape of the integration
GET /v1/verifications/{id}
Fetch the current status and result of a previously submitted verification.
GET /v1/verifications
List and filter verifications by type, status, reference or date range.
POST /v1/batches
Submit many verifications at once for back-office and reconciliation workflows.
Webhook: verification.completed
Delivered to your callback URL when a result is ready, signed so you can verify origin.
Webhook: verification.failed
Delivered when a check cannot complete, with the reason and whether a retry is sensible.
FAQs
Developer questions
Is there a sandbox?+
Yes. Sandbox keys and test subjects let you build and test the full flow, including webhooks, before touching live data.
How are webhooks secured?+
Each delivery is signed with a shared secret so your endpoint can verify that the payload came from MasterID before acting on it.
What happens on a duplicate submission?+
Send your own reference with each request and repeated submissions resolve to the same verification instead of creating a second one.
What are the rate limits?+
Throughput is set per organisation and sized with you during onboarding based on expected volume.
Get your API keys
Tell us the checks you need and we will provision sandbox access to start.