Skip to main content
The mock KYC endpoints let you build and test a sub-account KYC integration end-to-end without real documents and without calling the upstream provider. Each mock call still persists a real kyc_verifications row and recomputes the sub-account’s KYC status, so you exercise the same state machine your production flow will hit.
Mock endpoints live under the /sub-accounts/test/... path prefix and authenticate the same way as the real endpoints — your parent main account’s X-Auth-ID and X-Auth-Token headers.

​
Magic inputs

For PAN and GST, the document value you send selects the outcome:
Magic inputOutcome
TESTSUCCESS0001verified
TESTFAIL0001failed
TESTERROR0001HTTP 500 (simulated provider error)
TESTPENDING001pending — finalize later as verified
TESTPENDING_FAILpending — finalize later as failed
GST uses the same matrix, but the gstin must be a 15-character GSTIN-shaped value. TESTSUCCESS0001 is already 15 characters — use it as-is (do not append a suffix). Pad shorter magic inputs to 15 characters.
For the other steps:
StepMagic behavior
CIN searchReturns deterministic fake matches.
CIN confirmSucceeds when selected_cin starts with U72900KA2024PTC123456.
DigiLocker initiateReturns a deterministic access_request_id.
DigiLocker verifyMOCK_AR_SUCCESS → verified, MOCK_AR_FAIL → failed.

​
Endpoints

All paths are prefixed with https://api.vobiz.ai/api/v1/sub-accounts/test/{sub_auth_id}.
MethodPathDescription
POST/kyc/verify-panMock PAN — magic inputs above
POST/kyc/verify-gstMock GST — same matrix
POST/kyc/cin/searchMock CIN search
POST/kyc/cin/confirmMock CIN confirm
POST/kyc/digilocker/initiateMock DigiLocker initiate
POST/kyc/digilocker/verifyMock DigiLocker verify
POST/kyc/finalize-pendingFinalize a pending mock verification

​
Example: verified PAN

curl -X POST \
  "https://api.vobiz.ai/api/v1/sub-accounts/test/SA_XXXXXX/kyc/verify-pan" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "pan": "TESTSUCCESS0001" }'

{
  "verification_type": "pan",
  "status": "verified",
  "mock": true
}

​
Driving the async (pending) path

Some verifications complete asynchronously in production (e.g. provider returns later via webhook). To exercise that path in test mode without webhooks:
1

Submit a pending verification

Send a TESTPENDING001 (or TESTPENDING_FAIL) value. The verification is recorded as pending.
curl -X POST \
  "https://api.vobiz.ai/api/v1/sub-accounts/test/SA_XXXXXX/kyc/verify-pan" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "pan": "TESTPENDING001" }'
2

Finalize it

Promote the most recent pending mock verification of that type to a terminal outcome. verification_type ∈ pan | aadhaar | gst | cin; outcome ∈ verified | failed.
curl -X POST \
  "https://api.vobiz.ai/api/v1/sub-accounts/test/SA_XXXXXX/kyc/finalize-pending" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "verification_type": "pan", "outcome": "verified" }'
3

Confirm

Poll KYC status and confirm the verification flipped and kyc_calls_blocked updated as expected.
Test mode writes real rows against the sub-account’s KYC state. Use a dedicated test sub-account so a failed mock result doesn’t leave a production sub-account blocked.