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

Every real KYC endpoint has a test-mode counterpart under the /test/ path prefix. Test endpoints never hit Perfios or any external service. They accept magic input values that deterministically produce specific outcomes - useful for integration tests and CI pipelines. Test base path: 
/api/v1/sub-accounts/test/{sub_auth_id}/kyc/
All test endpoints use the same Authorization: Bearer {parent_jwt} header as the real endpoints. They write real kyc_verifications rows and recompute kyc_status, so the status endpoint reflects the mock outcome.

​
Magic input reference

Use these magic values in the main identifier field (e.g., pan, gstin, aadhaar_no) to trigger specific outcomes:
Magic inputOutcome
TESTSUCCESS0001verified - check passes immediately
TESTFAIL0001failed - check fails immediately
TESTERROR0001HTTP 500 - simulates an upstream error
TESTPENDING001pending - stays pending until finalized with verified
TESTPENDING_FAILpending - stays pending until finalized with failed

​
Mock endpoints

​
Mock PAN verification

POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/verify-pan
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "pan": "TESTSUCCESS0001"
}
Response (200) 
{
  "verification_type": "pan",
  "status": "verified",
  "sub_account_id": "SA_xxxxxxxx"
}

​
Mock GST verification

POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/verify-gst
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "gstin": "TESTSUCCESS0001GST"
}
Returns a deterministic list of fake company matches regardless of the company_name value. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/cin/search
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "company_name": "ACME"
}
Response (200) 
{
  "matches": [
    { "cin": "U72900KA2024PTC123456", "name": "ACME PRIVATE LIMITED", "state": "Karnataka" }
  ]
}

​
Mock CIN confirm

Succeeds when selected_cin starts with U72900KA2024PTC123456. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/cin/confirm
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "company_name": "ACME",
  "selected_cin": "U72900KA2024PTC123456"
}
Returns a deterministic mock access_key. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/aadhaar/consent
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "name": "Test User",
  "ip_address": "1.2.3.4"
}
Response (200) 
{
  "access_key": "MOCK_KEY"
}

​
Mock Aadhaar verify

Applies relaxed validation; any 12-digit aadhaar_no is accepted with the magic-input matrix. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/verify-aadhaar
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "aadhaar_no": "123456789012",
  "access_key": "MOCK_KEY"
}

​
Mock DigiLocker initiate

Returns a deterministic access_request_id without making an OAuth call. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/digilocker/initiate
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "redirect_url": "https://partner.example.com/kyc/callback"
}
Response (200) 
{
  "auth_link": "https://mock-digilocker.vobiz.ai/...",
  "access_request_id": "MOCK_AR_SUCCESS"
}

​
Mock DigiLocker verify

The outcome is controlled by the access_request_id value:
access_request_idOutcome
MOCK_AR_SUCCESSverified
MOCK_AR_FAILfailed
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/digilocker/verify
Authorization: Bearer {parent_jwt}
Content-Type: application/json

{
  "access_request_id": "MOCK_AR_SUCCESS"
}

​
Finalize a pending check

When you use TESTPENDING001 or TESTPENDING_FAIL, the verification stays in pending state. Use the finalize endpoint to advance it - simulating an async webhook without needing a real webhook server. 
POST /api/v1/sub-accounts/test/{sub_auth_id}/kyc/finalize-pending
Authorization: Bearer {parent_jwt}
Content-Type: application/json
Request body
FieldTypeRequiredDescription
verification_typestringYespan, aadhaar, gst, or cin
outcomestringYesverified or failed
{
  "verification_type": "pan",
  "outcome": "verified"
}
This promotes the most recent pending verification of the given type and recomputes kyc_calls_blocked on the sub-account.

KYC Overview

kyc_mode, business_type, and kyc_calls_blocked

Verification Methods (real)

Production PAN, GST, CIN, Aadhaar, DigiLocker endpoints