Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Sub-account KYC enables partners and resellers to enforce identity verification on each of their customers (sub-accounts) before allowing outbound calls. When a sub-account is created in customer_use mode, Vobiz automatically blocks all outbound calls until the required KYC checks are approved.

Real KYC

Perfios-backed PAN, GST, CIN, Aadhaar, and DigiLocker verification

Hosted Sessions

Email-link flow - customer completes KYC on the Vobiz-hosted widget

Test Mode

Mock endpoints with magic inputs for sandbox testing

​
KYC modes

Every sub-account has a kyc_mode field that controls whether KYC is enforced.
ModeBehaviourUse case
personal_useKYC not required; calls are never blocked for KYC reasons. Default.Internal teams, dev/test sub-accounts
customer_useKYC required; kyc_calls_blocked is set to true until all required verifications passCustomer-facing sub-accounts on a reseller platform

​
Setting kyc_mode on create

Pass kyc_mode in the request body when creating a sub-account. customer_use also requires an email field. 
POST /api/v1/accounts/{parent_auth_id}/sub-accounts/
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "name": "Customer Co",
  "email": "customer@example.com",
  "password": "Customer@12345",
  "kyc_mode": "customer_use",
  "business_type": "private_limited"
}
Response (201) - includes kyc_calls_blocked: true for a fresh customer_use sub-account.

​
Promoting an existing sub-account

PUT /api/v1/accounts/{parent_auth_id}/sub-accounts/{sub_auth_id}
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "kyc_mode": "customer_use"
}
The sub-account must already have an email address. The request returns 400 otherwise. On a successful mode change, kyc_calls_blocked is recomputed from the current verification state.

​
Business types

When creating or updating a sub-account in customer_use mode, pass one of the following values for business_type:
ValueEntity
individualIndividual / sole trader
proprietorshipSole proprietorship
private_limitedPrivate limited company
llpLimited Liability Partnership
partnershipPartnership firm
public_limitedPublic limited company
trustTrust
societySociety
hufHindu Undivided Family
governmentGovernment body

​
KYC status

Fetch the aggregated KYC state for a sub-account. The caller must be the parent main account (or an admin). 
GET /api/v1/sub-accounts/{sub_auth_id}/kyc/status
Authorization: Bearer {parent_jwt}
Response (200) 
{
  "sub_account_id": "SA_xxxxxxxx",
  "kyc_mode": "customer_use",
  "kyc_calls_blocked": true,
  "verifications": {
    "pan": "verified",
    "gst": "pending",
    "cin": null,
    "aadhaar": null,
    "digilocker": null
  }
}
FieldDescription
kyc_calls_blockedtrue when required verifications are incomplete; outbound calls are blocked
verificationsPer-method status - verified, failed, pending, or null (not attempted)

​
Verification methods

Choose the verification methods appropriate for your customer’s business type:
MethodEndpointBest for
PANPOST /kyc/verify-panAll entities
GSTPOST /kyc/verify-gstGST-registered businesses
CINPOST /kyc/cin/search + /cin/confirmRegistered companies
Aadhaar (OTP)POST /kyc/aadhaar/consent + /kyc/verify-aadhaarIndividuals
DigiLockerPOST /kyc/digilocker/initiate + /kyc/digilocker/verifyIndividuals (Aadhaar via OAuth)
See KYC Verification Methods for the full request/response details of each endpoint.

​
Authentication

All KYC endpoints authenticate as the parent main account using a JWT bearer token: 
Authorization: Bearer {parent_jwt}
The sub-account being verified is identified by {sub_auth_id} in the URL path, not by the auth header.

​
Next steps

Verification methods

PAN, GST, CIN, Aadhaar, and DigiLocker API reference

Hosted KYC session

Let customers complete KYC via a Vobiz-hosted email link

Test mode

Magic inputs for sandbox and CI testing

Sub-Accounts API

Full sub-account object reference