curl -X POST https://api.vouchmark.com/v1/kyb/widgets/wgt_aBcD.../applicants \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "your_ref_123",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
}
}'
{
"success": true,
"data": {
"applicant": {
"id": "app_aBcD...",
"widgetId": "wgt_aBcD...",
"environment": "live",
"status": "created",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
},
"referenceId": "your_ref_123",
"riskScore": null,
"decisionReason": null,
"moduleOrder": ["business_profile", "cac_verification", "tin_verification"],
"totalSpentKobo": 5000,
"startedAt": null,
"submittedAt": null,
"decidedAt": null,
"createdAt": "2026-06-01T10:00:00Z",
"updatedAt": "2026-06-01T10:00:00Z"
},
"sessionTransactionId": "txn_...",
"sessionChargeKobo": 5000
}
}
Onboarding (KYB)
Create applicant
Programmatically create an applicant under a widget.
POST
/
v1
/
kyb
/
widgets
/
{id}
/
applicants
curl -X POST https://api.vouchmark.com/v1/kyb/widgets/wgt_aBcD.../applicants \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "your_ref_123",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
}
}'
{
"success": true,
"data": {
"applicant": {
"id": "app_aBcD...",
"widgetId": "wgt_aBcD...",
"environment": "live",
"status": "created",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
},
"referenceId": "your_ref_123",
"riskScore": null,
"decisionReason": null,
"moduleOrder": ["business_profile", "cac_verification", "tin_verification"],
"totalSpentKobo": 5000,
"startedAt": null,
"submittedAt": null,
"decidedAt": null,
"createdAt": "2026-06-01T10:00:00Z",
"updatedAt": "2026-06-01T10:00:00Z"
},
"sessionTransactionId": "txn_...",
"sessionChargeKobo": 5000
}
}
Creates an applicant for a widget and opens its verification session, charging the session base fee to your wallet. Use this to start onboarding server-side instead of through the embedded widget.
Requires
Returns
Authorization: Bearer $TOKEN. Rate limited to 10 requests per minute.
Path parameters
Body
curl -X POST https://api.vouchmark.com/v1/kyb/widgets/wgt_aBcD.../applicants \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "your_ref_123",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
}
}'
{
"success": true,
"data": {
"applicant": {
"id": "app_aBcD...",
"widgetId": "wgt_aBcD...",
"environment": "live",
"status": "created",
"subject": {
"businessName": "Acme Trading Ltd",
"registrationNumber": "RC123456",
"email": "admin@acme.com"
},
"referenceId": "your_ref_123",
"riskScore": null,
"decisionReason": null,
"moduleOrder": ["business_profile", "cac_verification", "tin_verification"],
"totalSpentKobo": 5000,
"startedAt": null,
"submittedAt": null,
"decidedAt": null,
"createdAt": "2026-06-01T10:00:00Z",
"updatedAt": "2026-06-01T10:00:00Z"
},
"sessionTransactionId": "txn_...",
"sessionChargeKobo": 5000
}
}
201. The wrapper field for subject details is subject (not applicant). sessionTransactionId and sessionChargeKobo describe the wallet debit for opening the session.