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:
X-Auth-ID: {auth_id}
X-Auth-Token: {auth_token}

​
When KYC applies

kyc_modeKYC required?Notes
personal_use (default)NoThe sub-account inherits the parent account’s KYC.
customer_useYesThe sub-account must verify itself. Requires an email. Fresh sub-accounts start with kyc_calls_blocked: true.
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

Entity (business_type)Typical documents
individual, proprietorship, hufPAN + Aadhaar (via DigiLocker)
private_limited, public_limited, llp, partnershipPAN + GST and/or CIN
trust, society, governmentPAN + supporting registration (CIN/GST as applicable)

​
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

MethodEndpointDescription
GET/sub-accounts/{sub_auth_id}/kyc/statusAggregated KYC state
POST/sub-accounts/{sub_auth_id}/kyc/verify-panVerify PAN
POST/sub-accounts/{sub_auth_id}/kyc/verify-gstVerify GST
POST/sub-accounts/{sub_auth_id}/kyc/cin/searchCIN search
POST/sub-accounts/{sub_auth_id}/kyc/cin/confirmCIN confirm
POST/sub-accounts/{sub_auth_id}/kyc/digilocker/initiateDigiLocker initiate
POST/sub-accounts/{sub_auth_id}/kyc/digilocker/verifyDigiLocker verify
POST/sub-accounts/{sub_auth_id}/kyc-sessionsCreate a hosted KYC session
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.