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:

Per-document API

Drive each step yourself - PAN, GST, CIN, or Aadhaar via DigiLocker - and poll the aggregated status.

Hosted session

Hand the customer a Vobiz-hosted link (email) or redirect them inline to the hosted widget.

​
Document requirements by entity

​
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. Re-run that verification with corrected input to clear it.

​
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. Verify the documents the entity needs - authenticate as the parent, with the sub-account in the path. For a company: PAN then GST and/or CIN search → confirm. For an individual: PAN then DigiLocker initiate → verify.
  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.
Prefer to hand the customer a Vobiz-hosted form instead of driving each step? Use a hosted session and listen for webhooks.

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