Skip to main content
A customer_use sub-account must complete its own KYC before it can place calls. Until it does, the sub-account is returned with kyc_calls_blocked: true. This section documents the per-sub-account KYC API used to drive that verification.
Authentication: Sub-account KYC endpoints authenticate as the parent main account that owns the sub-account (or an admin), using your account’s X-Auth-ID and X-Auth-Token headers - the same credential pair used everywhere else in the API:

When KYC applies

Set kyc_mode at creation or promote an existing sub-account.

Verification paths

There are two ways to complete KYC for a customer_use sub-account:

Initialize KYC

Hand the customer a Vobiz-hosted link (email) or redirect them inline to the hosted widget. The widget collects PAN, GST, CIN, or Aadhaar via DigiLocker as the entity requires.

KYC status

Poll the aggregated status and the kyc_calls_blocked gate while the customer completes verification.

Document requirements by entity

The hosted widget asks the customer for the documents their entity type requires:

How the call-blocking gate works

Each verification persists a kyc_verifications row and recomputes the sub-account’s aggregated KYC state. The aggregated status exposes:
  • overall_status - not_started → pending → verified / failed.
  • verifications - the per-document state (pan, gst, cin, aadhaar), each not_started / pending / verified / failed.
  • kyc_calls_blocked - the gate. While true, the sub-account’s calls are rejected; it flips to false once the documents its business_type requires are verified.
A single failed document leaves kyc_calls_blocked: true. Create a new session so the customer can resubmit that document with corrected details.

Create → KYC → unblock recipe

  1. Create a customer_use sub-account with an email and a business_type. It returns kyc_calls_blocked: true. (Create)
  2. Initialize KYC - authenticate as the parent, with the sub-account in the path, and create a hosted session. Email the customer a signed link or redirect them to the widget, and listen for webhooks to learn the outcome.
  3. Poll KYC status until kyc_calls_blocked is false.
  4. The sub-account can now place calls with its own credentials. See the full onboarding flow.

Endpoints

Building an integration? Use Test Mode to drive verified / failed / pending outcomes with magic inputs - no real documents and no calls to the upstream provider.