Create applicant

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
  }
}

POST

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

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
  }
}

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

Overview

Auth

Companies

Verifications

Onboarding (KYB)

Widget Embed (Runtime)

Trust Badge

Monitoring

Investigations

Disputes

Vouch AI

Compliance

Wallet & Billing

Developers

Path parameters

Body

​Path parameters

​Body

Path parameters

Body