Integration API Documentation

API Curl

API_1

API_2

Base URL

https://<your-domain>.test.getkwikid.com

Authentication

All endpoints except token generation require JWT authentication.

Header:

auth: jwt_token

Endpoints

1. Generate Token

POST /agentapi/v1/agent/generate_token

Generates a JWT token for API authentication.

Request Body:

{
  "username": "<your_username>",
  "password": "<your_password>"
}

Required Fields:

Field	Type	Character Length	Validation	Description
username	string	3-20	alphanumeric	Username for authentication
password	string	8-32	alphanumeric	Password for authentication

200 Success:

{
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..GFKV8h5mgGd4BRlMzPY6R92fO4IzWwMGxc6Y9YDoXXw",
  "status_code": 200,
  "success": true
}

Response Fields:

Key	Type	Character Length	Description
Token	string	Variable (JWT)	JWT token for authentication
status_code	integer	3	HTTP status code indicating the result
success	boolean	N/A	Indicates whether the request was successful

401 Unauthorized:

{
  "msg": "username/password did not match",
  "status_code": 401,
  "success": true
}

Response Fields:

Key	Type	Character Length	Description
msg	string	Variable	Error message describing the issue
status_code	integer	3	HTTP status code indicating the result
success	boolean	N/A	Indicates whether the request was successful

400 Bad Request:

{
  "msg": "please provide valid username and password",
  "status_code": 400,
  "success": true
}

Response Fields:

Key	Type	Character Length	Description
msg	string	Variable	Error message describing the issue
status_code	integer	3	HTTP status code indicating the result
success	boolean	N/A	Indicates whether the request was successful

429 Rate limit:

{
  "status": 429,
  "message": "Rate limit exceeded"
}

Response Fields:

Key	Type	Character Length	Description
status	integer	3	HTTP status code for rate limiting
message	string	Variable	Message indicating the rate limit exceeded

2. Send KYC Link

POST /agentapi/v1/agent/sendLink/

Generates and sends a KYC link to the customer.

Headers:

auth: jwt_token
accept: application/json

Request Body:

{
  "user_id": "1234567890",
  "phone_number": "7710978566",
  "send_notification": 1,
  "link_type": "free",
  "extras": {
    "last_kyc_date": "1691154990",
    "link_expires_in": "900"
  }
}

Required Fields:

Field	Type	Description
user_id	string	Unique identifier for the user
phone_number	string	User's phone number
send_notification	integer	Whether to send notification (0/1)
link_type	string	Type of link to generate (e.g., "free"), case-sensitive

200 Success:

{
    "link_expiry_time": "1745308158.1170702",
    "link_id": "3bKabcAF2AWK",
    "link_url": "https://<your-domain>.test.getkwikid.com/user/%3Fl%3D3bKabcAF2AWK%26d%3D1%26s%3D0",
    "phone_number": "1234567890",
    "session_id": "8b19b5c9-36de-47a2-9cb8-1025f36da034",
    "user_id": "1234567894",
    "validity_duration": 900
}

Response Fields:

Key	Type	Character Length	Description
link_expiry_time	string	Variable	Expiry time of the link in epoch format
link_id	string	Variable	Unique identifier for the link
link_url	string	Variable	URL for accessing the resource
phone_number	string	10	User's phone number
session_id	string	Variable	Unique identifier for the session
user_id	string	Variable	Unique identifier for the user
validity_duration	integer	Variable	Duration in seconds for which the link is valid
message	string	Variable	Error message for unauthorized or bad requests
status	integer	3	HTTP status code indicating the result
msg	string	Variable	Error message for internal server errors

Error Responses:

401 Unauthorized

{
  "message": "Token is invalid"
}

Response Fields:

Key	Type	Character Length	Description
message	string	Variable	Error message indicating token issue

400 Bad Request

<!doctype html>
<html lang=en>
  <title>400 Bad Request</title>
  <h1>Bad Request</h1>
  <p>The browser (or proxy) sent a request that this server could not understand.</p>
</html>

500 Internal Server Error

{
  "msg": "error message",
  "status": 500
}

Response Fields:

Key	Type	Character Length	Description
msg	string	Variable	Error message indicating server issue
status	integer	3	HTTP status code for internal error

429 Rate limit

{
  "status": 429,
  "message": "Rate limit exceeded"
}

Response Fields:

Key	Type	Character Length	Description
status	integer	3	HTTP status code for rate limiting
message	string	Variable	Message indicating rate limit exceeded

3. Get Session Details

GET /agentapi/v1/session/get_details/{SESSION_ID}

Retrieves detailed information about a specific KYC session.

Headers:

auth: jwt_token
accept: application/json

Path Parameters:

Parameter	Type	Description
SESSION_ID	string	Unique identifier for the session

Response Codes:

200 Success

{
  "session_data": {
    "IS_VIDO_UPLOADED": true/ false,
    "aadhaar_request_time": "timestamp",
    "aadhaar_url": "aadhaar_front_url",
    "aadhaarback_url": "aadhaar_back_url",
    "agent_assignment_time": "timestamp",
    "agent_id": "agent_identifier",
    "agent_region": "region_name",
    "agent_screen_url": "agent_screen_video_url",
    "agent_tl": null,
    "agent_video_url": "agent_video_url",
    "captured_images": ["selfie", "pan", "aadhaar", ... other doc list],
    "client_name": "client_name",
    "customer_IP": "ip_address",
    "end_time": "timestamp",
    "extras": {
      "applicant_name": "applicant_name",
      "current_address": "address",
      "current_employer_name": "employer_name",
      "institute_name": "institute_name",
      "loan_amt": "loan_amount",
      "pan_number": "pan_number",
      "session_status": "status",
      "session_type": "VKYC",
      "user_ip": "ip_address"
    },
    "feedback": "{\"type\":\"Approve\",\"comment\":\"All Successful\"}",
    "link_id": "link_identifier",
    "number_of_videos_uploaded": 2,
    "origin": "KWIKID_ID",
    "pan_request_time": "timestamp",
    "pan_url": "pan_url",
    "phone_number": "phone_number",
    "selfie_request_time": "timestamp",
    "selfie_url": "selfie_url",
    "session_id": "session_id",
    "session_status": "kyc_result_approved",
    "start_time": "timestamp",
    "summary_data": {
      "agent_id": "agent_id",
      "client_name": "client_name",
      "docs": [
        {
          "name": "Pan Card",
          "details": {},
          "front_url": "url"
        },
        {
          "name": "Aadhaar Card",
          "details": {},
          "facematch_score": {},
          "front_url": "url"
        },
        {
          "name": "Signature Match",
          "validator": {
            "success": false,
            "type": "isSignatureVerify"
          }
        },
        ... other doc list
      ],
      "overall_summary": [
        {"success": true, "title": "Selfie"},
        {"success": true, "title": "Pan Card"},
        {"success": true, "title": "Aadhaar Card"},
        null,
        {"success": true, "title": "Qna"}
      ],
      "qna": [
        {"q": "Question?", "a": "Answer"}
      ],
      "user_info": {
        "location": "location_address",
        "latitude": 0.0,
        "longitude": 0.0,
        "user_id": "user_id"
      }
    },
    "summary_json_url": "summary_url",
    "user_ack": 1,
    "user_id": "user_id",
    "user_video_url": "user_video_url",
    "vkyc_start_time": "timestamp",
    "zip_url": "zip_url"
  },
  "status": 200
}

Response Fields:

Key	Type	Character Length	Description
session_data	object	N/A	Contains all session-related data
IS_VIDO_UPLOADED	boolean	N/A	Indicates if the video has been uploaded
aadhaar_request_time	string	Variable	Timestamp for Aadhaar request
aadhaar_url	string	Variable	URL for Aadhaar front document
aadhaarback_url	string	Variable	URL for Aadhaar back document
agent_assignment_time	string	Variable	Timestamp for agent assignment
agent_id	string	Variable	Identifier for the agent
agent_region	string	Variable	Region of the agent
agent_screen_url	string	Variable	URL for the agent's screen video
agent_tl	null	N/A	Team leader identifier (if applicable)
agent_video_url	string	Variable	URL for the agent's video
captured_images	array	Variable	List of captured images
client_name	string	Variable	Name of the client
customer_IP	string	Variable	IP address of the customer
end_time	string	Variable	Timestamp for the end of the session
extras	object	N/A	Additional information about the session
feedback	string	Variable	Feedback in JSON format
link_id	string	Variable	Identifier for the link
number_of_videos_uploaded	integer	N/A	Count of videos uploaded
origin	string	Variable	Origin identifier
pan_request_time	string	Variable	Timestamp for PAN request
pan_url	string	Variable	URL for PAN document
phone_number	string	10	Phone number of the user
selfie_request_time	string	Variable	Timestamp for selfie request
selfie_url	string	Variable	URL for the selfie document
session_id	string	Variable	Identifier for the session
session_status	string	Variable	Status of the session
start_time	string	Variable	Timestamp for the start of the session
summary_data	object	N/A	Summary data of the session
summary_json_url	string	Variable	URL for the summary JSON
user_ack	integer	N/A	User acknowledgment status
user_id	string	Variable	Identifier for the user
user_video_url	string	Variable	URL for the user's video
vkyc_start_time	string	Variable	Timestamp for the start of VKYC
zip_url	string	Variable	URL for the zip file
status	integer	3	HTTP status code indicating the result

Session Status Values:

session_status	Remarks
`waiting`	link is sent
`agent_alloted`	User opens the link for preassigned call
`kyc_request_accepted`	Agent accepted the call
`kyc_request_rejected`	Agent rejects call
`kyc_result_rejected`	When KYC result is rejected at the end. Auto reject if result is pending after expiry
`kyc_result_approved`	When agent approves the session at the end
`session_expired`	When scheduled call gets cancelled. Link validity expires for that session
`user_abandoned`	User disconnected for a time longer than configured `user_abandoned_timer`
`vkyc_requested`	When user schedules a call
`kyc_rejected`	Agent has a pre-existing link attached. If a new link is assigned, old gets rejected

401 Unauthorized

{
  "message": "Missing authorization header"
}

Response Fields:

Key	Type	Character Length	Description
message	string	Variable	Error message indicating token issue

400 Bad Request

{
  "e": "list index out of range",
  "msg": "Invalid session id",
  "status": 400
}

Response Fields:

Key	Type	Character Length	Description
e	string	Variable	Error message indicating session issue
msg	string	Variable	Error message indicating session issue
status	integer	3	HTTP status code for session issue

500 Internal Server Error

<!doctype html>
<html lang=en>
<title>500 Internal Server Error</title>
<h1>Internal Server Error</h1>
<p>The server encountered an internal error and was unable to complete your request.</p>

429 Rate limit

{
  "status": 429,
  "message": "Rate limit exceeded"
}

Response Fields:

Key	Type	Character Length	Description
status	integer	3	HTTP status code for rate limiting
message	string	Variable	Message indicating rate limit exceeded

4. Push User Data

POST /appapi/v1/dkyc/push_user_data

Pushes user data for digital KYC (DKYC) processing. It automates the KYC workflow by initiating a session, processing form data, and handling verification.

Headers:

Header	Value
accept	application/json
auth	jwt_token
Content-Type	application/json

Request Body:

{
    "data": [
        {
            "step_info": {
                "doc_type": "forms",
                "label": "Personal Information Collection"
            },
            "user_form_data": {
                "BASIC_INFORMATION": { ... },
                "FAMILY_INFORMATION": { ... },
                "PERSONAL_INFORMATION": { ... }
            }
        },
        {
            "step_info": {
                "doc_type": "forms",
                "label": "Address Information"
            },
            "user_form_data": {
                "COMMUNICATION_ADDRESS": { ... },
                "PERMANENT_ADDRESS": { ... }
            }
        },
        {
            "step_info": {
                "doc_type": "forms",
                "label": "Verification Information"
            },
            "user_form_data": {
                "IDENTITY_VERIFICATION": { ... },
                "INPERSON_VERIFICATION": { ... }
            }
        },
        {
            "step_info": {
                "doc_type": "forms",
                "label": "FATCA Declaration"
            },
            "user_form_data": {
                "FATCA_DECLARATION": { ... }
            }
        },
        {
            "step_info": {
                "doc_type": "forms",
                "label": "Document Collection"
            },
            "user_form_data": {
                "DOCUMENT_COLLECTION": { ... }
            }
        }
    ],
    "extras": {
        "location": {
            "address": "Full address string",
            "latitude": 19.10817,
            "longitude": 72.903107
        }
    },
    "phone_number": "1212121212",
    "user_id": "dkyc-test-01"
}

Request Parameters:

Name	Type	Description	Mandatory
user_id	string	Unique identifier for the user	Yes
phone_number	string	User's phone number	Yes
data	array	Array of form data objects structured by step	Yes
extras	object	Additional contextual information	No

Form Data Fields:

BASIC_INFORMATION Fields

Field Path	Type	Description	Valid Values	Mandatory
BASIC_INFORMATION.uploadType	string	Type of upload	"03"	Yes
BASIC_INFORMATION.pan	string	PAN number	Format: AAAAA1234A	Yes
BASIC_INFORMATION.dob	string	Date of birth	Format: DD-MON-YYYY	Yes
BASIC_INFORMATION.amc	string	AMC code	e.g., "TEST_AMC"	Yes
BASIC_INFORMATION.ipvDate	string	IPV date	Format: DD-MON-YYYY	Yes
BASIC_INFORMATION.uidNo	string	UID/Aadhaar number	12-digit number	Yes
BASIC_INFORMATION.ekycType	string	eKYC type	"I"	Yes
BASIC_INFORMATION.kycType	string	KYC type	"1", "2", "3", "4", "5"	Yes

PERSONAL_INFORMATION Fields

Field Path	Type	Description	Valid Values	Mandatory
PERSONAL_INFORMATION.applicantTitle	string	Title of applicant	"Mr", "Mrs", "Miss", "Dr"	Yes
PERSONAL_INFORMATION.applicantFirstName	string	First name of applicant	-	Yes
PERSONAL_INFORMATION.applicantMiddleName	string	Middle name of applicant	-	No
PERSONAL_INFORMATION.applicantLastName	string	Last name of applicant	-	Yes
PERSONAL_INFORMATION.gender	string	Gender	"M", "F", "T"	Yes
PERSONAL_INFORMATION.maritalStatus	string	Marital status	"01", "02", "03"	Yes
PERSONAL_INFORMATION.occupation	string	Occupation code	"01" through "13", "99"	Yes
PERSONAL_INFORMATION.applicantCitizenship	string	Citizenship code	"01" (Indian), "02" (Other)	Yes
PERSONAL_INFORMATION.applicantStatus	string	Applicant status	"R", "N", "P", "I"	Yes

FAMILY_INFORMATION Fields

Field Path	Type	Description	Valid Values	Mandatory
FAMILY_INFORMATION.relationship	string	Relationship type	"F" (Father), "S" (Spouse)	Yes
FAMILY_INFORMATION.fatherTitle	string	Title of father	"Mr", "Mrs"	Yes
FAMILY_INFORMATION.fatherFirstName	string	First name of father	-	Yes
FAMILY_INFORMATION.fatherMiddleName	string	Middle name of father	-	No
FAMILY_INFORMATION.fatherLastName	string	Last name of father	-	Yes
FAMILY_INFORMATION.motherTitle	string	Title of mother	-	No
FAMILY_INFORMATION.motherFirstName	string	First name of mother	-	No
FAMILY_INFORMATION.motherMiddleName	string	Middle name of mother	-	No
FAMILY_INFORMATION.motherLastName	string	Last name of mother	-	No

COMMUNICATION_ADDRESS Fields

Field Path	Type	Description	Valid Values	Mandatory
COMMUNICATION_ADDRESS.commAddress1	string	Address line 1	-	Yes
COMMUNICATION_ADDRESS.commAddress2	string	Address line 2	-	No
COMMUNICATION_ADDRESS.commAddress3	string	Address line 3	-	No
COMMUNICATION_ADDRESS.commpincode	string	PIN/Postal code	-	Yes
COMMUNICATION_ADDRESS.commCity	string	City	-	Yes
COMMUNICATION_ADDRESS.commDistrict	string	District	-	Yes
COMMUNICATION_ADDRESS.commState	string	State	-	Yes
COMMUNICATION_ADDRESS.commCountry	string	Country code	-	Yes
COMMUNICATION_ADDRESS.commMobileNoCode	string	Mobile country code	"91"	Yes
COMMUNICATION_ADDRESS.commMobileNo	string	Mobile number	-	Yes
COMMUNICATION_ADDRESS.commEmailId	string	Email address	-	Yes
COMMUNICATION_ADDRESS.comAddresstype	string	Address type	"01" through "05"	Yes
COMMUNICATION_ADDRESS.commAddressProof	string	Address proof type	"01" through "33" (except "30")	Yes
COMMUNICATION_ADDRESS.commIdentityNo	string	Identity number for address proof	-	Yes

PERMANENT_ADDRESS Fields

Field Path	Type	Description	Valid Values	Mandatory
PERMANENT_ADDRESS.perAddress1	string	Address line 1	-	Yes
PERMANENT_ADDRESS.perAddress2	string	Address line 2	-	No
PERMANENT_ADDRESS.perAddress3	string	Address line 3	-	No
PERMANENT_ADDRESS.perPincode	string	PIN/Postal code	-	Yes
PERMANENT_ADDRESS.perCity	string	City	-	Yes
PERMANENT_ADDRESS.perDistrict	string	District	-	Yes
PERMANENT_ADDRESS.perState	string	State	-	Yes
PERMANENT_ADDRESS.perCountry	string	Country code	-	Yes
PERMANENT_ADDRESS.perAddressProof	string	Address proof type	-	Yes
PERMANENT_ADDRESS.peridentityNo	string	Identity number for address proof	-	Yes

IDENTITY_VERIFICATION Fields

Field Path	Type	Description	Valid Values	Mandatory
IDENTITY_VERIFICATION.idProof	string	ID proof type	"01" through "15"	Yes
IDENTITY_VERIFICATION.idProofIdentityNo	string	Identity number	-	Yes
IDENTITY_VERIFICATION.aaplicantKycAccType	string	KYC account type	"01"	Yes

INPERSON_VERIFICATION Fields

Field Path	Type	Description	Valid Values	Mandatory
INPERSON_VERIFICATION.ipvDoneBy	string	Name of person who did IPV	-	Yes
INPERSON_VERIFICATION.ipvEmployeeBranch	string	Employee branch	-	Yes
INPERSON_VERIFICATION.ipvEmployeeCode	string	Employee code	-	Yes
INPERSON_VERIFICATION.ipvEmployeeDesignation	string	Employee designation	-	Yes
INPERSON_VERIFICATION.ipvEmployeeName	string	Employee name	-	Yes
INPERSON_VERIFICATION.ipvInstitutionCode	string	Institution code	-	Yes
INPERSON_VERIFICATION.ipvInstitutionName	string	Institution name	-	Yes
INPERSON_VERIFICATION.kycDate	string	KYC date	Format: DD-MON-YYYY	Yes

FATCA_DECLARATION Fields

Field Path	Type	Description	Valid Values	Mandatory
FATCA_DECLARATION.fatcataxJurisdiction	string	FATCA tax jurisdiction flag	"Y", "N"	Yes
FATCA_DECLARATION.fatcaRelPerson	string	FATCA related person flag	"N"	Yes
FATCA_DECLARATION.dobDeclaration	string	Date of birth declaration	Format: DD-MON-YYYY	Yes
FATCA_DECLARATION.placeDeclaration	string	Place of declaration	-	Yes
FATCA_DECLARATION.kraInfo	string	KRA info	"eKYC-eIPV"	Yes
FATCA_DECLARATION.panCopy	string	PAN copy flag	"Y"	Yes
FATCA_DECLARATION.exmtCat	string	Exemption category	"N"	Yes

DOCUMENT_COLLECTION Fields

Field Path	Type	Description	Valid Values	Mandatory
DOCUMENT_COLLECTION.docAddressProof	string	Address proof document	Base64 or URL	Yes
DOCUMENT_COLLECTION.docPhoto	string	Photo document	Base64 or URL	Yes
DOCUMENT_COLLECTION.docSign	string	Signature document	Base64 or URL	Yes
DOCUMENT_COLLECTION.docPerVerVideo	string	Verification video	Base64 or URL	Yes
DOCUMENT_COLLECTION.appDocAddrProofCorrespondence	string	Correspondence address proof	Base64 or URL	Yes
DOCUMENT_COLLECTION.docEsignForm	string	E-sign form	Base64 or URL	Yes

Response:

Status Code	Description
200	Success, data processed successfully
400	Invalid request parameters
500	Internal server error

200 Success:

{
  "success": true,
  "session_id": "<session_id>",
  "track": {
    "user_id": "<user_id>",
    "session_id": "<session_id>"
  }
}

Field	Type	Description
success	boolean	Operation success status
session_id	string	Unique session identifier
track.user_id	string	User ID from request
track.session_id	string	Session ID created for this request

400 Bad Request:

{
  "msg": "Invalid request format",
  "status_code": 400,
  "success": false,
  "track": {
    "user_id": null,
    "session_id": null
  },
  "errors": {
    "missing_fields": ["field1", "field2"],
    "incorrect_formats": ["field3"]
  }
}

Field	Type	Description
msg	string	Error message
status_code	integer	HTTP status code
success	boolean	Operation success status (false)
track	object	Tracking information (may be null)
errors	object	Validation error details

500 Internal Server Error:

{
  "msg": "An internal error occurred",
  "status_code": 500,
  "success": false,
  "track": {
    "user_id": "<user_id>",
    "session_id": "<session_id>"
  }
}

Field	Type	Description
msg	string	Error message
status_code	integer	HTTP status code
success	boolean	Operation success status (false)
track	object	Tracking information if available

429 Rate limit

{
  "status": 429,
  "message": "Rate limit exceeded"
}

Best Practices

1. Token Management

Store the JWT token securely
Refresh the token before it expires
Include the token in all authenticated requests

2. Error Handling

Implement proper error handling for all API responses
Log errors for debugging purposes
Implement retry logic for transient failures

3. Data Validation

Validate all input data before sending to the API
Ensure required fields are present
Format data according to API specifications

4. Rate Limiting

Implement rate limiting in your application
Handle 429 (Too Many Requests) responses appropriately

API Integrations

Integration API Documentation

API Curl

Base URL

Authentication

Endpoints

1. Generate Token

200 Success:

401 Unauthorized:

400 Bad Request:

429 Rate limit:

2. Send KYC Link

200 Success:

401 Unauthorized

400 Bad Request

500 Internal Server Error

429 Rate limit

3. Get Session Details

200 Success

401 Unauthorized

400 Bad Request

500 Internal Server Error

429 Rate limit

4. Push User Data

200 Success:

400 Bad Request:

500 Internal Server Error:

429 Rate limit

Best Practices

On this page