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 acustomer_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 akyc_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), eachnot_started/pending/verified/failed.kyc_calls_blocked- the gate. Whiletrue, the sub-account’s calls are rejected; it flips tofalseonce the documents itsbusiness_typerequires areverified.
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
- Create a
customer_usesub-account with anemailand abusiness_type. It returnskyc_calls_blocked: true. (Create) - 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.
- Poll KYC status until
kyc_calls_blockedisfalse. - The sub-account can now place calls with its own credentials. See the full onboarding flow.