> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create applicant

> Programmatically create an applicant under a widget.

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

<ParamField path="id" type="string" required>
  The widget ID to create the applicant under.
</ParamField>

## Body

<ParamField body="referenceId" type="string">
  Your internal ID to link this applicant to your system. 1–120 characters.
</ParamField>

<ParamField body="subject" type="object" default="{}">
  Subject details for the business being verified. All sub-fields are optional.
</ParamField>

<ParamField body="subject.businessName" type="string">Up to 200 characters.</ParamField>
<ParamField body="subject.registrationNumber" type="string">Up to 120 characters.</ParamField>
<ParamField body="subject.tin" type="string">Up to 40 characters.</ParamField>
<ParamField body="subject.email" type="string">Valid email, up to 200 characters.</ParamField>
<ParamField body="subject.phone" type="string">Up to 40 characters.</ParamField>
<ParamField body="subject.jurisdiction" type="string">Up to 80 characters.</ParamField>
<ParamField body="subject.industry" type="string">Up to 120 characters.</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

Returns `201`. The wrapper field for subject details is `subject` (not `applicant`). `sessionTransactionId` and `sessionChargeKobo` describe the wallet debit for opening the session.