Skip to main content
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 Authorization: Bearer $TOKEN. Rate limited to 10 requests per minute.

​
Path parameters

​
id
string
required
The widget ID to create the applicant under.

​
Body

​
referenceId
string
Your internal ID to link this applicant to your system. 1–120 characters.
​
subject
object
default:"{}"
Subject details for the business being verified. All sub-fields are optional.
​
subject.businessName
string
Up to 200 characters.
​
subject.registrationNumber
string
Up to 120 characters.
​
subject.tin
string
Up to 40 characters.
​
subject.email
string
Valid email, up to 200 characters.
​
subject.phone
string
Up to 40 characters.
​
subject.jurisdiction
string
Up to 80 characters.
​
subject.industry
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
  }
}
Returns 201. The wrapper field for subject details is subject (not applicant). sessionTransactionId and sessionChargeKobo describe the wallet debit for opening the session.