Customer Session Creation API

This API initiates a new VKYC session for a customer. Once it is triggered successfully, the response carries a unique VKYC URL that the customer is redirected to in order to complete the verification.

POSThttps://sandbox/api/v1/vkyc/create/customer/

Content-Type: application/json

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <access_token> from the Auth Token API.
Content-Type	string	Yes	application/json.

Request payload

The body has four objects: customer_details, aadhaar_details, time_details and document_details.

{
  "customer_details": {
    "customer_identifier": "<value>",
    "cif_type": "<Individual or Non-Individual>",
    "consent_to_open_account": true,
    "business_name": "<value (if cif_type is Non-Individual)>",
    "name": "<value>",
    "email": "<value>",
    "mobile_number": "<value>",
    "aadhar_number": "<value>",
    "pan_card_number": "<value>",
    "aadhaar_ref_number": "<value>",
    "latitude": "<value>",
    "longitude": "<value>",
    "system_ip": "<value>",
    "gender": "<value>",
    "dob": "<dd-mm-yyyy>",
    "permanent_addressline1": "<value>",
    "permanent_addressline2": "<value>",
    "permanent_addressline3": "<value>",
    "permanent_city": "<value>",
    "permanent_state": "<value>",
    "permanent_district": "<value>",
    "permanent_country": "<value>",
    "permanent_pincode": "<value>",
    "father_name": "<value>",
    "mother_name": "<value>",
    "spouse_name": "<value>",
    "maritial_status": "<value>",
    "place_of_birth": "<value>",
    "occupation": "<value>",
    "annual_income": "<value>",
    "nationality": "<value>",
    "communication_addressline1": "<value>",
    "communication_addressline2": "<value>",
    "communication_addressline3": "<value>",
    "communication_city": "<value>",
    "communication_district": "<value>",
    "communication_state": "<value>",
    "communication_country": "<value>",
    "communication_pincode": "<value>",
    "branch_sol_id": "<value>",
    "branch_name": "<value>",
    "company_name": "<value>",
    "title": "<value>",
    "religion": "<value>",
    "is_ex_service_man": "<boolean>",
    "is_manual_scavenger": "<boolean>",
    "is_politically_exposed_person": "<boolean>",
    "is_person_with_disability": "<boolean>",
    "is_communication_same_permanent": "<boolean>",
    "communication_address_proof": "<value>",
    "opt_in_home_loan": "<boolean>",
    "opt_in_vehicle_loan": "<boolean>",
    "opt_in_education_loan": "<boolean>",
    "opt_in_business_loan": "<boolean>",
    "opt_in_personal_loan": "<boolean>",
    "agriculture_land_area": "<value>",
    "is_general_ews": "<boolean>",
    "employer_name": "<value>",
    "employer_type": "<value>",
    "employee_code": "<value>"
  },
  "aadhaar_details": {
    "aadhar_name": "<value>",
    "aadhar_image": "<value>",
    "aadhar_yob": "<value>",
    "aadhar_sex": "<value>",
    "aadhar_address": "<value>",
    "aadhar_num": "<value>"
  },
  "time_details": {
    "adhar_verified_time": "<value>",
    "pan_verified_time": "<value>",
    "otpsend_time": "<value>",
    "otp_resend_time": "<value>",
    "validated_time": "<value>"
  },
  "document_details": {
    "signature_image": "<value>",
    "pan_image": "<value>",
    "poa_communication_image": "<value>",
    "gst_or_udhyam_image": "<value>"
  }
}

:::info Changes in this version

• The document object key was renamed from doc_details to document_details.
• aadhar_yob now carries a full date in YYYY-MM-DD format.
• pan_card_number must be unique for each customer. :::

Parameter specification

customer_details

Parameter	Type	Mandatory	Length	Description / Examples
customer_identifier	string	Yes	50	Unique identifier for each customer.
cif_type	string	Yes	20	Type of customer entity: Individual, Non-Individual.
consent_to_open_account	boolean	Yes	—	Whether the customer consented to open the account.
business_name	string	Conditional	100	Name of the business. Mandatory when cif_type is Non-Individual.
name	string	Yes	80	Full name of the customer.
email	string	Yes	65	Customer's email address, e.g. user@example.com.
mobile_number	string	Yes	15	Customer's registered mobile number.
aadhar_number	string	Yes	12	12-digit Aadhaar number, masked — e.g. XXXXXXXX1234.
pan_card_number	string	Yes	10	10-character alphanumeric PAN, e.g. ABCDE1234F. Unique per customer.
aadhaar_ref_number	string	Yes	32	Reference number generated during Aadhaar offline KYC.
latitude	string	Yes	22	Live latitude captured during onboarding.
longitude	string	Yes	22	Live longitude captured during onboarding.
system_ip	string	Yes	20	System IP address.
gender	string	Yes	25	Customer's gender — M / F / T.
dob	string	Yes	10	Date of birth in dd-mm-yyyy.
permanent_addressline1	string	Yes	100	First line of the permanent address.
permanent_addressline2	string	No	100	Second line of the permanent address. May be null.
permanent_addressline3	string	No	100	Third line of the permanent address. May be null.
permanent_city	string	Yes	50	City of the permanent address.
permanent_state	string	Yes	50	State of the permanent address.
permanent_district	string	Yes	50	District of the permanent address.
permanent_country	string	Yes	50	Country of the permanent address.
permanent_pincode	string	Yes	10	Postal code of the permanent address.
father_name	string	Yes	80	Customer's father's full name.
mother_name	string	Yes	80	Customer's mother's full name.
spouse_name	string	Conditional	80	Customer's spouse's full name.
maritial_status	string	Yes	20	Marital status, e.g. MARRIED, UNMARRIED, SINGLE.
place_of_birth	string	Yes	50	City or town of birth.
occupation	string	Yes	50	Line of work or job title.
annual_income	string	Yes	20	Income bracket or exact amount.
nationality	string	Yes	50	Nationality of the customer.
communication_addressline1	string	Conditional	100	First line of the communication address. Required when is_communication_same_permanent is false.
communication_addressline2	string	Conditional	100	Second line of the communication address.
communication_addressline3	string	Conditional	100	Third line of the communication address.
communication_city	string	Conditional	50	City of the communication address.
communication_district	string	Conditional	50	District of the communication address.
communication_state	string	Conditional	50	State of the communication address.
communication_country	string	Conditional	50	Country of the communication address.
communication_pincode	string	Conditional	10	Postal code of the communication address.
branch_sol_id	string	Yes	20	SOL ID of the selected branch.
company_name	string	No	100	Employer's company name. May be null.
title	string	Yes	10	Salutation, e.g. Mr., Mrs., Dr..
religion	string	Yes	50	Religion of the customer, e.g. HINDU ST.
is_ex_service_man	boolean	Yes	—	Whether the customer is an ex-serviceman.
is_manual_scavenger	boolean	Yes	—	Manual scavenger status.
is_politically_exposed_person	boolean	Yes	—	Whether the customer is a politically exposed person (PEP).
is_person_with_disability	boolean	Yes	—	Physical disability flag.
is_communication_same_permanent	boolean	Yes	—	true when the communication and permanent addresses are the same.
communication_address_proof	string	No	50	Document submitted as communication address proof, e.g. Voter ID.
opt_in_home_loan	boolean	No	—	Customer opted for the home loan cross-sell.
opt_in_vehicle_loan	boolean	No	—	Customer opted for the vehicle loan cross-sell.
opt_in_education_loan	boolean	No	—	Customer opted for the education loan cross-sell.
opt_in_business_loan	boolean	No	—	Customer opted for the business loan cross-sell.
opt_in_personal_loan	boolean	No	—	Customer opted for the personal loan cross-sell.
agriculture_land_area	string	No	50	Size of agricultural land owned, e.g. 2. May be null.
is_general_ews	boolean	No	—	Economically Weaker Section status.
employer_name	string	No	100	Name of the candidate's employer. May be null.
employer_type	string	No	50	Type of employer, e.g. Govt, Private, MNC. May be null.
employee_code	string	No	50	Employee ID or code. May be null.

aadhaar_details

Parameter	Type	Mandatory	Length	Description / Examples
aadhar_name	string	Yes	100	Full name of the customer as printed on the Aadhaar card.
aadhar_image	string	Yes	—	Base64-encoded string or URL of the Aadhaar photo.
aadhar_yob	string	Yes	10	Date of birth in YYYY-MM-DD.
aadhar_sex	string	Yes	10	Gender as per Aadhaar, e.g. Male, Female.
aadhar_address	string	Yes	255	Full address string fetched from Aadhaar XML / verification.
aadhar_num	string	Yes	12	12-digit Aadhaar number, or the masked form XXXXXXXX1234.

time_details

Parameter	Type	Mandatory	Length	Description / Examples
adhar_verified_time	string	Yes	30	Timestamp of Aadhaar verification, e.g. 2024-02-27T10:15:30Z.
pan_verified_time	string	No	30	Timestamp of PAN verification. May be null.
otpsend_time	string	No	30	Timestamp the mobile OTP was first sent. May be null.
otp_resend_time	string	No	30	Timestamp of the OTP resend request, if any. May be null.
validated_time	string	No	30	Timestamp the OTP was successfully validated. May be null.

document_details

Parameter	Type	Mandatory	Length	Description / Examples
signature_image	string	No	—	Base64 string or URL of the customer's wet signature. May be null.
pan_image	string	No	—	Base64 string or URL of the physical PAN card photo. May be null.
poa_communication_image	string	Conditional	—	Base64 string or URL of the submitted Proof of Address document.
gst_or_udhyam_image	string	No	—	Base64 string or URL of the business proof (GST / Udyam certificate). May be null.

Sample payload

{
  "customer_details": {
    "customer_identifier": "jhhjshdf",
    "cif_type": "Individual",
    "consent_to_open_account": true,
    "business_name": "",
    "name": "Mohan Kumar",
    "email": "mohan@example.com",
    "mobile_number": "7500580045",
    "aadhar_number": "********1234",
    "pan_card_number": "ZCCDE0060K",
    "aadhaar_ref_number": "A123456789",
    "latitude": "9.9312",
    "longitude": "76.2673",
    "gender": "M",
    "dob": "15-08-1995",
    "permanent_addressline1": "House No 12",
    "permanent_addressline2": "MG Road",
    "permanent_addressline3": "Near Metro Station",
    "permanent_city": "Kollam",
    "permanent_state": "Kerala",
    "permanent_district": "Ernakulam",
    "permanent_country": "India",
    "permanent_pincode": "682001",
    "father_name": "Ramesh Sharma",
    "mother_name": "Sita Sharma",
    "maritial_status": "MARRIED",
    "spouse_name": "Reefa",
    "place_of_birth": "Kochi",
    "occupation": "Parking / garages",
    "system_ip": "103.168.0.203",
    "annual_income": "800000",
    "nationality": "Indian",
    "communication_addressline1": "House No 12",
    "communication_addressline2": "MG Road",
    "communication_addressline3": "",
    "communication_city": "Kochi",
    "communication_district": "Ernakulam",
    "communication_state": "Kerala",
    "communication_country": "India",
    "communication_pincode": "682001",
    "account_scheme": "10691101",
    "branch_sol_id": "MAHB0000018",
    "title": "Mrs.",
    "religion": "HINDU ST",
    "is_ex_service_man": false,
    "is_manual_scavenger": false,
    "is_politically_exposed_person": false,
    "is_person_with_disability": true,
    "is_communication_same_permanent": false,
    "communication_address_proof": "ADHAR WITH SAME ADDRESS",
    "opt_in_home_loan": false,
    "opt_in_vehicle_loan": true,
    "opt_in_education_loan": false,
    "opt_in_business_loan": false,
    "opt_in_personal_loan": true,
    "agriculture_land_area": "0",
    "is_general_ews": true,
    "employer_name": "Tech Solutions Pvt Ltd",
    "employer_type": "Private",
    "employee_code": "EMP12345"
  },
  "aadhaar_details": {
    "aadhar_name": "Mohan Kumar",
    "aadhar_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "aadhar_yob": "1995-12-11",
    "aadhar_sex": "Male",
    "aadhar_address": "House No 12, MG Road, Kochi, Kerala, 682001",
    "aadhar_num": "********1234"
  },
  "time_details": {
    "adhar_verified_time": "2026-04-28T12:00:00Z",
    "pan_verified_time": "2026-03-17T10:02:00Z",
    "otpsend_time": "2026-03-17T10:05:00Z",
    "otp_resend_time": "2026-03-17T10:06:00Z",
    "validated_time": "2026-03-17T10:10:00Z"
  },
  "document_details": {
    "signature_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "pan_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "poa_communication_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "gst_or_udhyam_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

Image fields are shown truncated — send the complete base64 data URI or a URL.

Example

POST/api/v1/vkyc/create/customer/

curl --location 'https://sandbox/api/v1/vkyc/create/customer/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
  "customer_details": {
    "customer_identifier": "jhhjshdf",
    "cif_type": "Individual",
    "name": "Mohan Kumar",
    "email": "mohan@example.com",
    "mobile_number": "7500580045",
    "pan_card_number": "ZCCDE0060K",
    "dob": "15-08-1995"
  },
  "aadhaar_details": { },
  "time_details": { },
  "document_details": { }
}'

200

{
"status": true,
"status_code": 200,
"message": "Success",
"data": {
  "unique_id": "<System-generated unique ID>",
  "customer_identifier": "<Customer id>",
  "customer_redirect_url": "https://redirecturl"
}
}

Success response

200 application/json

Field	Type	Description
status	boolean	true for a successful request.
status_code	integer	HTTP status code echoed in the body.
message	string	Human-readable message describing the outcome.
data.unique_id	string	Unique internal customer ID generated by the VKYC application. Use it for the Status Check API.
data.customer_identifier	string	The customer ID you sent in the request.
data.customer_redirect_url	string	URL the customer must be redirected to in order to begin the VKYC session.

Failure response

400 application/json — validation error.

{
  "status": false,
  "status_code": 400,
  "message": "Bad Request",
  "data": {
    "status": false,
    "status_code": 400,
    "data": {
      "customer_details": {
        "dob": ["Enter a valid date in DD-MM-YYYY format."]
      }
    },
    "error_code": "invalid"
  }
}

Field	Type	Description
status	boolean	Always false when validation fails.
status_code	integer	HTTP status code echoed in the body.
message	string	High-level description of what failed.
data.data	object	Key-value pairs showing which fields failed and why, in DRF error style.
data.error_code	string	Machine-readable error code, e.g. invalid.

HTTP response codes

HTTP code	Status	When returned
200 OK	Success	The request succeeded and the customer session was created.
400 Bad Request	Client error	The request failed validation on the input data.
401 Unauthorized	Auth error	The API key, merchant code or token is missing or invalid.
403 Forbidden	Forbidden	The client is authenticated but not allowed to access the resource.
406 Not Acceptable	False	The application is currently under process.
409 Conflict	Conflict	A duplicate session or customer already exists for the identifiers provided.
422 Unprocessable Entity	Validation failed	Input is syntactically correct but semantically invalid, e.g. a failed format check.
500 Internal Server Error	Server error	An unexpected error occurred on the server side.
503 Service Unavailable	Service down	The VKYC service is temporarily unavailable or under maintenance.