> ## 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.

# Run module

> Execute a specific verification module for an applicant.

Runs a single verification module for an applicant and charges the module cost to your wallet. The module ID is a path parameter. Returns the run, the updated applicant, and the amount charged.

Requires `Authorization: Bearer $TOKEN`. Rate limited to 30 requests per minute.

## Path parameters

<ParamField path="applicantId" type="string" required>
  The applicant ID.
</ParamField>

<ParamField path="moduleId" type="string" required>
  The module to run. Must be enabled on the widget. One of: `business_profile`, `industry_classification`, `cac_verification`, `tin_verification`, `scuml`, `tax_clearance`, `business_license`, `address_verification`, `bank_account_verification`, `operational_proof`, `directors_kyc`, `shareholders_kyc`, `beneficial_ownership`, `liveness_check`, `document_upload`, `aml_screening`, `pep_screening`, `sanctions_screening`, `adverse_media`.
</ParamField>

## Body

<ParamField body="units" type="integer" default="1">
  Number of units to run. Integer, 1–20.
</ParamField>

<ParamField body="input" type="object" default="{}">
  Module-specific input data. Required fields vary by module.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.vouchmark.com/v1/kyb/applicants/app_aBcD.../modules/cac_verification/run \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "units": 1,
      "input": {
        "registrationNumber": "RC123456"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "run": {
        "id": "run_aBcD...",
        "applicantId": "app_aBcD...",
        "widgetId": "wgt_aBcD...",
        "moduleId": "cac_verification",
        "actionKey": "kyb_cac_verification",
        "status": "passed",
        "units": 1,
        "chargedKobo": 15000,
        "walletTransactionId": "txn_...",
        "score": 92,
        "result": { "companyName": "ACME TRADING LTD", "rcNumber": "RC123456", "status": "ACTIVE" },
        "errorMessage": null,
        "startedAt": "2026-06-01T10:10:00Z",
        "completedAt": "2026-06-01T10:10:03Z",
        "createdAt": "2026-06-01T10:10:00Z"
      },
      "applicant": {
        "id": "app_aBcD...",
        "widgetId": "wgt_aBcD...",
        "environment": "live",
        "status": "in_progress",
        "subject": { "businessName": "Acme Trading Ltd", "registrationNumber": "RC123456" },
        "referenceId": "your_ref_123",
        "riskScore": null,
        "decisionReason": null,
        "moduleOrder": ["business_profile", "cac_verification", "tin_verification"],
        "totalSpentKobo": 20000,
        "startedAt": "2026-06-01T10:05:00Z",
        "submittedAt": null,
        "decidedAt": null,
        "createdAt": "2026-06-01T10:00:00Z",
        "updatedAt": "2026-06-01T10:10:03Z"
      },
      "chargedKobo": 15000
    }
  }
  ```
</ResponseExample>

Returns `201`. A run's `status` is one of `pending`, `passed`, `failed`, or `requires_review`.