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
string
required
The widget ID to create the applicant under.
Body
string
Your internal ID to link this applicant to your system. 1–120 characters.
object
default:"{}"
Subject details for the business being verified. All sub-fields are optional.
string
Up to 200 characters.
string
Up to 120 characters.
string
Up to 40 characters.
string
Valid email, up to 200 characters.
string
Up to 40 characters.
string
Up to 80 characters.
string
Up to 120 characters.
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.