> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate Video KYC Request
> Use this API to generate a Video KYC verification link for a user and send it through the configured notification channels (SMS, email, or WhatsApp). The message content can be configured using user and agent templates.
**Template Behaviour**: Including Aadhaar details in this request skips the DigiLocker verification step, reducing the user journey from 3 steps to 2. See [User Templates](/api-reference/vrs/v2/video-kyc/vkyc-descriptions#user-templates) for details.
## OpenAPI
````yaml post /vkyc
openapi: 3.0.0
info:
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
email: developers@cashfree.com
name: API Support
url: https://discord.com/invite/QdZkNSxXsB
title: Cashfree Verification API's.
version: '2023-12-18'
description: >-
Cashfree's Verification APIs provide different types of verification to our
merchants.
servers:
- description: Sandbox Server
url: https://sandbox.cashfree.com/verification
- description: Production Server
url: https://api.cashfree.com/verification
security: []
tags:
- name: Aadhaar
description: Operations related to Aadhaar verification.
- name: BAV V2
description: Operations related to Bank account verification v2.
- name: PAN
description: Operations related to PAN verification.
- name: Digilocker
description: Operations related to Digilocker verification.
- name: E-sign
description: Operations related to E-sign verification.
- name: Reverse Penny Drop
description: Operations related to Reverse Penny Drop verification.
- name: UPI Penny Drop
description: Operations related to UPI Penny Drop verification.
- name: Mobile Penny Drop
description: Operations related to Mobile Penny Drop verification.
- name: IP
description: Operation related to IP verification.
- name: UPI
description: Operations related to UPI verification.
- name: Passport
description: Operation related to Passport verification.
- name: CIN
description: Operation related to CIN verification.
- name: Name Match
description: Operation related to Name Match verification.
- name: PAN to GSTIN
description: Operation related to PAN to GSTIN.
- name: Face Match
description: Operation related to Face Match verification.
- name: Voter ID
description: Operation related to Voter ID verification.
- name: Reverse Geocoding
description: Operation related to Reverse Geocoding.
- name: Vehicle RC
description: Operation related to Vehicle RC verification.
- name: Driving License
description: Operation related to Driving License verification.
- name: GSTIN
description: Operation related to GSTIN verification.
- name: Account Aggregator
description: Operations related to Account aggregator.
- name: OTPLess
description: Operations related to OTPLess Verification.
- name: 1-Click
description: Operations related to 1-Click.
- name: Smart OCR
description: Operations related to Smart OCR.
- name: Geocoding
description: Operations related to Geocoding.
- name: Udyam
description: Operation related to Udyam verification.
- name: PAN to Udyam
description: Operation related to PAN to Udyam.
paths:
/vkyc:
post:
tags:
- VKYC
summary: Initiate Video KYC Request
description: >-
Use this API to generate a Video KYC verification link for a user and
send it through the configured notification channels (SMS, email, or
WhatsApp). The message content can be configured using user and agent
templates.
operationId: VrsInitiateVKYC
parameters:
- $ref: '#/components/parameters/x_cf_signature'
- $ref: '#/components/parameters/global_x_api_version'
requestBody:
$ref: '#/components/requestBodies/VKYCLinkRequest'
responses:
'200':
$ref: '#/components/responses/VKYCLinkResponse'
'400':
$ref: '#/components/responses/Response400VkycLink'
'401':
$ref: '#/components/responses/Response401'
'403':
$ref: '#/components/responses/Response403'
'404':
$ref: '#/components/responses/InitiateVKYC404Response'
'422':
$ref: '#/components/responses/Response422'
'429':
$ref: '#/components/responses/Response429'
'500':
$ref: '#/components/responses/Response500V2'
security:
- XClientID: []
XClientSecret: []
components:
parameters:
x_cf_signature:
description: >-
Send the signature if two-factor authentication is selected as Public
Key. [More
details](https://www.cashfree.com/docs/api-reference/vrs/getting-started#2fa-api-signature-generation).
name: x-cf-signature
in: header
required: false
schema:
type: string
example: ''
global_x_api_version:
description: API version to be used. Format is in YYYY-MM-DD.
name: x-api-version
in: header
required: true
schema:
type: string
default: '2024-12-01'
example: '2024-12-01'
example: '2024-12-01'
requestBodies:
VKYCLinkRequest:
description: Request parameters to generate Video KYC link.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VKYCLinkRequestSchema'
examples:
NonSeamless:
summary: non-seamless flow
description: >-
Generation Video KYC Link using Cashfree generated
user_reference_id.
value:
verification_id: vkyc_verification_id
user_template: vkyc_user_template_v1
agent_template: vkyc_agent_template_v2
user_reference_id: 1234
notification_types:
- sms
- whatsapp
Seamless:
summary: seamless flow (sdk)
description: Passing aadhaar, pan details in Video KYC Link API.
value:
verification_id: vkyc_verification_id
user_template: vkyc_user_template_v1
agent_template: vkyc_agent_template_v2
user_reference_id: 13214
notification_types:
- sms
- whatsapp
aadhaar_details:
last_verified_at: '2025-05-07T15:04:05Z'
care_of: 'S/O: Fakkirappa Dollin'
dob: 02-02-1995
gender: M
name: Mallesh Fakkirappa Dollin
split_address:
country: India
dist: Haveri
house: Shri Kanaka Nilaya
pincode: 581115
po: Ranebennur
state: Karnataka
street: Umashankar Nagar 1st Main 5th Cross
subdist: Ranibennur
vtc: Ranibennur
photo_link:
security_questions:
- order: 1
question: What is your father's name?
answer: John Snow
- order: 2
question: What is your salary?
answer: '1000000'
responses:
VKYCLinkResponse:
description: Success response for generating a Video KYC link.
content:
application/json:
schema:
$ref: '#/components/schemas/VKYCLinkResponseSchema'
examples:
Success:
value:
verification_id: vkyc_verification_id
reference_id: 1358
user_reference_id: 11174
status: RECEIVED
sub_status: LINK_GENERATED
vkyc_link: https://forms.cashfree.com/verification/s7ml5i0
user_id: vkyc_user_id1
link_expiry: '2024-02-02T00:00:00.000Z'
aadhaar_details:
last_verified_at: '2025-05-06 15:04:05'
care_of: 'S/O: Fakkirappa Dollin'
dob: 02-02-1995
gender: M
name: Mallesh Fakkirappa Dollin
address_details:
country: India
dist: Haveri
house: Shri Kanaka Nilaya
pincode: 581115
po: Ranebennur
state: Karnataka
street: Umashankar Nagar 1st Main 5th Cross
subdist: Ranibennur
vtc: Ranibennur
photo_link:
security_questions:
- order: 1
question: What is Your name ?
answer: John Doe
auditor_remarks: null
agent_remarks: Pan not available during video call
Response400VkycLink:
description: Validation errors for Video KYC Link API.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
Verification ID Missing:
$ref: '#/components/examples/VerificationIdMissing'
Verification ID With Special Chars:
$ref: '#/components/examples/VerificationIdWithSpecialCharacter'
Invalid User Id:
value:
type: validation_error
code: user_id_value_invalid
message: User Id entered is invalid.
User Id Missing:
value:
type: validation_error
code: user_id_number_missing
message: user_id is missing in the request.
Invalid Verification Id:
value:
type: validation_error
code: verification_id_value_invalid
message: verification ID entered is invalid.
Verification Id Missing:
value:
type: validation_error
code: verification_id_value_missing
message: verification_id is missing in the request.
Invalid User Template Name:
value:
type: validation_error
code: user_template_value_invalid
message: user template entered doesn't exists.
User Template Name Missing:
value:
type: validation_error
code: user_template_value_missing
message: user_template is missing in the request.
Invalid Agent Template Name:
value:
type: validation_error
code: agent_template_value_invalid
message: agent template name entered doesn't exists.
Agent Template Name Missing:
value:
type: validation_error
code: agent_template_value_missing
message: agent_template is missing in the request.
Client ID/Client Secret in Missing:
$ref: '#/components/examples/XClientIdMissing'
Using-Test-Credentials-in-Prod:
$ref: '#/components/examples/UsingTestCredentialsInProd'
Response401:
description: Invalid client ID and client secret combination.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
Invalid client ID and client secret combination:
value:
type: authentication_error
code: authentication_failed
message: Invalid clientId and clientSecret combination
Response403:
description: Authentication error (IP not whitelisted).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
IP not whitelisted:
value:
type: authentication_error
code: ip_validation_failed
message: >-
IP not whitelisted your current ip is 106.51.91.104.For IP
whitelisting assistance, visit our guide at
https://www.cashfree.com/docs/secure-id/get-started/integration/ip-whitelisting-verification
x-cf-signature header missing:
value:
type: validation_error
code: authentication_failed
message: x-cf-signature missing in the request header
InitiateVKYC404Response:
description: Not found errors in Initiate Video KYC.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
User reference id not found:
value:
type: validation_error
code: user_reference_id_not_found
message: user_reference_id does not exist
User id not found:
value:
type: validation_error
code: user_id_not_found
message: user_id does not exist
Response422:
description: >-
Validation error because of insufficient balance to process this
request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
Insufficient balance:
value:
type: validation_error
code: insufficient_balance
message: Insufficient balance to process this request
Response429:
description: Rate limit exceed error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
Rate limit error per operation:
value:
type: rate_limit_error
code: too_many_requests_per_operation
message: Too many requests for this operation, rate limit reached
Rate limit error per IP:
value:
type: rate_limit_error
code: too_many_requests_per_ip
message: Too many requests from the IP, rate limit reached
Response500V2:
description: Internal error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseSchema'
examples:
Internal Server Error:
value:
type: internal_error
code: verification_failed
message: something went wrong
schemas:
VKYCLinkRequestSchema:
type: object
example:
value:
verification_id: vkyc_verification_id
user_template: vkyc_user_template_v1
agent_template: vkyc_agent_template_v2
user_reference_id: 8713
notification_types:
- sms
- whatsapp
aadhaar_details:
last_verified_at: '2025-05-07T15:04:05Z'
care_of: 'S/O: Fakkirappa Dollin'
dob: 02-02-1995
gender: M
name: Mallesh Fakkirappa Dollin
split_address:
country: India
dist: Haveri
house: Shri Kanaka Nilaya
pincode: 581115
po: Ranebennur
state: Karnataka
street: Umashankar Nagar 1st Main 5th Cross
subdist: Ranibennur
vtc: Ranibennur
year_of_birth: 1995
photo_link: <
security_questions:
- order: 1
question: What is your father's name?
answer: John Snow
- order: 2
question: What is your first pet's name?
answer: Oreo
required:
- verification_id
properties:
verification_id:
type: string
description: >-
It is the unique ID you create to identify the verification request.
The maximum character limit is 50. Only alphaumeric, period (.),
hyphen (-), and underscore ( _ ) are allowed.
example: vkyc_verification_id
default: vkyc_verification_id
user_template:
type: string
description: >-
It is the name of users vkyc template [more
details](https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#user-template-user-template).
example: vkyc_user_template_v1
default: vkyc_user_template_v1
agent_template:
type: string
description: >-
It is the name of agents vkyc template [more
details](https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#agent-template-agent-template).
example: vkyc_agent_template_v2
default: vkyc_agent_template_v2
user_reference_id:
type: integer
description: >-
It is the unique ID created by Cashfree Payments that you receive in
the response of Create User for Secure ID API.
example: 1358
default: 1358
user_id:
description: >-
It is the unique ID you create to identify the user in Create User
for Secure ID API.
type: string
example: User0123
default: User0123
notification_types:
type: array
description: >-
List of notification types that should be triggered for this
request.
items:
type: string
example:
- sms
- whatsapp
default:
- sms
- whatsapp
aadhaar_details:
$ref: '#/components/schemas/AadhaarDetails'
security_questions:
$ref: '#/components/schemas/SecurityQuestion'
VKYCLinkResponseSchema:
type: object
properties:
verification_id:
type: string
description: >-
It displays the unique ID you created to identify the verification
request.
example: test053
reference_id:
type: integer
description: >-
It displays the unique ID created by Cashfree Payments for reference
purposes. format: `int64`
example: 10042
status:
type: string
description: >-
It displays the status of the API request. Refer to [this
link](https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#status-substatus-mapping)
for all possible values and their meanings.
example: PRE_VIDEO_CALL
sub_status:
type: string
description: >-
It displays the sub status of the API request. Refer to [this
link](https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#status-substatus-mapping)
for all possible values and their meanings.
example: AADHAAR_VERIFICATION_SUCCESS
vkyc_link:
type: string
description: It displays the URL of the vKYC form to be filled by the user.
example: https://forms.cashfree.com/verification/M8go0i1k9fvg
link_expiry:
type: string
format: date
description: The date on which the vKYC link will expire.
example: '2025-05-30T00:00:00.000Z'
user_reference_id:
type: string
description: The reference ID of the user for whom the VKYC link is generated.
example: 123456
user_id:
type: string
description: The user ID of the user for whom the VKYC link is generated.
example: User0123
aadhaar_details:
type: object
description: Aadhaar information associated with the user.
properties:
last_verified_at:
type: string
format: date-time
description: Timestamp when Aadhaar was last verified.
example: '2025-05-06T15:04:05.000Z'
care_of:
type: string
description: It displays the parent/guardian of the user.
example: Jerripothula Koteswrara Rao
dob:
type: string
description: It displays the date of birth of the user.
example: 02-02-1995
gender:
type: string
description: It displays the gender of the user.
example: M
name:
type: string
description: It displays the name of the user.
example: Mallesh Fakkirappa Dollin
photo_link:
type: string
description: It displays the URL to the image present in the aadhaar card.
example: >-
https://cf-prod-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/51826/10042/photo-link/photo.jpg
split_address:
type: object
description: Split address as extracted from Aadhaar.
properties:
country:
description: >-
It displays the name of the country as present in the
aadhaar card of user.
type: string
example: India
dist:
description: >-
It displays the name of the dist as present in the aadhaar
card of user.
type: string
example: Haveri
house:
description: >-
It displays the house name/number as present in the aadhaar
card of user.
type: string
example: Shri Kanaka Nilaya
pincode:
description: >-
It displays the PIN code information as present in the
aadhaar card of user.
type: integer
example: 581115
po:
description: >-
It displays the post office nearest to the address present
in the aadhaar card of user.
type: string
example: Ranebennur
state:
description: >-
It displays the name of the state as present in the aadhaar
card of user.
type: string
example: Karnataka
street:
description: >-
It displays the name of the street as present in the aadhaar
card of user.
type: string
example: Umashankar Nagar 1st Main 5th Cross
subdist:
description: >-
It displays the name of the sub district as present in the
aadhaar card of user.
type: string
example: Ranibennur
vtc:
description: >-
It displays the village, town, city information as present
in the aadhaar card of user.
type: string
example: Ranibennur
security_questions:
type: array
description: List of security questions and answers.
items:
type: object
properties:
question:
type: string
description: Security question asked to the user.
example: What is your fathers's name ?
answer:
type: string
description: Answer provided by the user.
example: John
order:
type: integer
description: Order of the security question.
example: 1
auditor_remarks:
type: string
nullable: true
description: Remarks provided by the auditor during the Video KYC process.
example: Verification completed successfully
agent_remarks:
type: string
nullable: true
description: Remarks provided by the agent during the Video KYC process.
example: Pan not available during video call
ErrorResponseSchema:
type: object
properties:
code:
type: string
example: x-client-id_missing
error:
type: object
example:
ref_id: 102
message:
type: string
example: x-client-id is missing in the request.
description: It displays the outcome of the error.
type:
type: string
example: validation_error
description: It displays the type of error.
AadhaarDetails:
type: object
properties:
last_verified_at:
type: string
format: date-time
example: '2025-05-07T15:04:05Z'
care_of:
type: string
example: 'S/O: Fakkirappa Dollin'
dob:
type: string
format: date
example: 02-02-1995
gender:
type: string
enum:
- M
- F
- O
example: M
name:
type: string
example: Mallesh Fakkirappa Dollin
split_address:
$ref: '#/components/schemas/Address'
photo_link:
type: string
format: uri
example:
required:
- name
- dob
- gender
- care_of
- address_details
- last_verified_at
- photo_link
SecurityQuestion:
type: array
items:
type: object
properties:
order:
type: integer
example: 1
question:
type: string
example: What is your father's name?
answer:
type: string
example: John Snow
required:
- question
- answer
- order
Address:
type: object
properties:
country:
type: string
example: India
dist:
type: string
example: Haveri
house:
type: string
example: Shri Kanaka Nilaya
pincode:
type: integer
example: 581115
po:
type: string
example: Ranebennur
state:
type: string
example: Karnataka
street:
type: string
example: Umashankar Nagar 1st Main 5th Cross
subdist:
type: string
example: Ranibennur
vtc:
type: string
example: Ranibennur
required:
- country
- state
- dist
- pincode
- house
- street
examples:
VerificationIdMissing:
value:
type: validation_error
code: verification_id_missing
message: verification_id is missing in the request.
VerificationIdWithSpecialCharacter:
value:
type: validation_error
code: verification_id_value_invalid
message: >-
verification_id can include only alphanum, dot, hyphen and
underscores.
XClientIdMissing:
value:
type: validation_error
code: x-client-id_missing
message: x-client-id is missing in the request.
UsingTestCredentialsInProd:
value:
type: validation_error
code: x-client-secret_value_invalid
message: Client secret belongs to test environment
securitySchemes:
XClientID:
type: apiKey
in: header
name: x-client-id
description: >-
Your unique client identifier issued by Cashfree. You can find this in
your [Merchant
Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
XClientSecret:
type: apiKey
in: header
name: x-client-secret
description: >-
The secret key associated with your client ID. Use this to authenticate
your API requests. You can find this in your [Merchant
Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
````