Digitap.

ai CKYC SDK Suite

API Doc & Integration Guide
(Version 1.40, 5 Jan, 2024)

A jumpstart guide to boosting your Business

Save Time, Save Cost

1
 Table of Contents

1 Introduction 3
1.1 CKYC SDK Suite Introduction 3
2 API Documentation 3
2.1 Introduction 3
2.2 URLs 3
2.3 Client Requirements 4
2.4 API Request & Response Format 4
2.5 HTTP Status/Response Codes and its response body format 5
2.5.1 Error Messages 6
2.6 API Result 6
3 CKYC - Search API 7
3.1 API Introduction 7
3.2 API Request 7
3.3 API Success Response 9
3.3.1 Successful Validation (result_code 101) Case 9
3.3.2 Unsuccessful Validation Cases 9
3.4 API Failure Response 9
.5 Additional Notes 10
4 CKYC - Download API 10
4.1 API Introduction 10
4.2 API Request 10
4.3 API Success Response 11
4.3.1 Successful Validation (result_code 101) Case 11
4.3.2 Unsuccessful Validation Case 14
4.4 API Failure Response 14
5 CKYC - Advanced API 14
5.1 API Introduction 14
5.2 API Request 15
5.3 API Success Response 16
5.3.1 Successful Validation (result_code 101) Case 16
5.3.2 Partial Validation 19
5.3.3 Unsuccessful Validation Case 20
5.4 API Failure Response 20
5.5 Additional Notes 20

2
1 Introduction
This document is intended for our enterprise partners who can easily integrate the services they
have chosen with Digitap.ai. Using this document they can jumpstart their business processes
and start using the Digitap.ai services as early as possible and also align their own business
processes seamlessly by integrating and making changes to their backend.

1.1 CKYC SDK Suite Introduction

Digitap.ai Validation SDK Suite provides APIs to validate the various aspects of an end
customer or legal entity including

❏ CKYC Search (Retrieve CKYC Number with basic details)

❏ CKYC Download (Download complete CKYC details of user)
❏ CKYC Advanced (Integration of ‘CKYC Search’ & ‘CKYC Download’ in one flow)

Note: Digitap.ai reserves the right to modify this API documentation from time-to-time. If you are
a business using this Service, you will be notified well in advance, prior to any change being
made.

2 API Documentation

2.1 Introduction
Digitap.ai CKYC (Central KYC) Suite provides RESTful/standard HTTP Web APIs which help to
validate a specific data point by providing the response synchronously in the same API Call.
The API uses the standard HTTP status/response codes to indicate the success or API errors.

2.2 URLs
Following is the base URL for UAT & production Environment.
Production SDK Env <Client Specific URL>

Production Env https://api.digitap.ai/

UAT/DEMO Env https://apidemo.digitap.work/

3
Following are the URLs for various APIs:

<base_url>/ckyc/v1/search Searching CKYC ID of customer

<base_url>/ckyc/v1/download Downloading CKYC details of customer

<base_url>/ckyc/v1/advanced Advanced CKYC details of customer

2.3 Client Requirements

The following are mandatory requirements from the enterprise end to integrate the CKYC API
Solution:

● Institution Certificate (in .pem format or .pfx format)

● Institution Private Key (in .key format)
● Institution Financial Code (eg. INXXXX)

For on-premise CKYC SDK Solution, the requirements are mentioned below:

● AWS Requirements:
- IAM User
- Lambda Function
- Lambda Layer
- API Gateway

NB: Whitelist outbound IP of the server / VPC where the dedicated infrastructure code is
deployed. The IP will be shared by the Digitap team.

2.4 API Request & Response Format

● Both the input request and response follow the JSON format.
● In each APIs input, a client reference number is accepted to easily identify the given
request from a client and the same is also mirrored in the output. The other parameters
required in the input and their format are explained in specific APIs.
● The API error is normally returned as standard HTTP Status/Response Codes and also
mirrored in the body of the response.
● When the API request is accepted, HTTP status code 200 is returned and whether the
validation is successful or not is returned in the result_code. The various possible values
of the validation is explained under the section “API Result”

4
 ● In all the responses, an unique request-id (unique UUID) would be returned, which can
be used for easier debugging in the future. Clients are requested to provide this
request-id when raising an issue or discussing the response.

2.5 HTTP Status/Response Codes and its response body format

The API Error Codes are returned as HTTP Status Codes. Following status codes would be
returned by the APIs.

Code Message Description

200 OK Request Successful

(Note: 200 does not mean that Validation is
success, but indicates that the request is
successful. result_code in the Response
body indicates whether the validation is
successful or not).

400 One or more parameters format Input parameter passed by the customer is
is wrong missing or invalid

500 Internal Error 1/ 2/ 3 Internal Server Error identified through its

number

504 Endpoint request Timed out The response latency from the source for
authentication is >30sec.

Format of the response body for successful request case (http Status code 200) is like below:

{
"http_response_code": 200,
"client _ref_num": "abcd123",
"request_id": "97a9f2ce-cd70-11ea-ba26-4ef9447da577",
"result_code":nnn,

// Optional items based on result_code

"result":nnn,
"message":"yyy",
}

5
Format of the response body for failure cases (http Status code other than 200) is like below:

{
"http_response_code": nnn,
"client _ref_num": "abcd123",
"request_id": "97a9f2ce-cd70-11ea-ba26-4ef9447da577",
"error": "xxxx
}

2.5.1 Error Messages

Error messages for each of the failure cases is given below:

Code Error Message

400 One or more parameters format is wrong or missing

500 Internal Error 1/2/3

503 Website is in maintenance

504 Endpoint request Timed out

Please see the respective APIs for any additional details.

2.6 API Result

When the API returns HTTP status code 200/OK, the API request is accepted and result of the
request is provided in the key called “result_code” in the response body:
{
"http_response_code": 200,
"client _ref_num": "abcd123",
"request_id": "97a9f2ce-cd70-11ea-ba26-4ef9447da577",
"result_code": nnn,
}

Various possible values of result_code and is tabled below:

6
 result_code Description

101 Validation Successful

102 Invalid id number or combination of inputs

103 No record found for the given input

108 If the user’s application is rejected

Please see the respective APIs for details of which result code occurs in the specific API.

3 CKYC - Search API

3.1 API Introduction
This API helps to retrieve the CKYC ID of an individual / legal entity along with a few other basic
details of the KYC user like name, father’s name, formal image and others. The Search API is
very flexible and supports numerous Government issued ID types.

3.2 API Request

● Method: POST

● Header:

Key Mandatory/Optional Value

(M/O)

content-type M JSON/application

authorization M Type: Basic Auth, Username:client_id,

password:client_secret
/
BasicBase64encodedValueOf
(client_id:client_secret)

● Request Body:

7
 Key Mandatory/ Value
Optional
(M/O)

client_ref_num M Unique ID for the OCR request from the Client side
[Max of 45 chars]

identifier M Any Govt. issued ID (number)

identifier_type M Any Govt. issued ID (name) *refer below

identifier_type Description

PASSPORT Passport number of the individual.

VOTER_ID Voter ID number of the individual.

PAN PAN of the individual / entity.

Pattern:
^[A-Za-z]{4}[[A-Za-z]{1}\d{4}[A-Za-z]{1}$

DL Driving license of the individual.

PROOF_OF_AADHAAR PSV (pipe separated values) version of:

Last 4 characters of Aadhaar

Individual’s name
DOB (DD-MM-YYYY)
Gender (M / F / T)

Example:
6080|JACOB SINGH|20-10-1990|M

NGREGA NGREGA Job Card ID

NPR National Population Registry Letter Code

CKYC_ID CKYC ID of the individual / entity.

CIN CIN of the entity.

Pattern:
^([L|U]{1})([0-9]{5})([A-Za-z]{2})([0-9]{4})([A-Za-z]
{3})([0-9]{6})$

RC Registration Certificate.

8
3.3 API Success Response

3.3.1 Successful Validation (result_code 101) Case

When the CKYC search details are retrieved successfully, result_code 101 would be returned.
The response format for the same is as follows:

{
"http_response_code": 200,
"client _ref_num": "abcd123",
"request_id": "97a9f2ce-cd70-11ea-ba26-4ef9447da577",
"result_code": "101",
"result": {
"status": "VALID",
"name": "JOHN SINGH",
"fathers_name": "JACOB SINGH",
"age": "44",
"kyc_date": "21-10-2019",
"photo": (base64 encoded string),
"remarks": null,
"ckyc_id": "90022545959659",
}
}

3.3.2 Unsuccessful Validation Cases

The following response would be provided in case if the CKYC search fails.

{
"http_response_code": 200,
"result_code": "103",
"request_id": "97a9f2ce-cd70-11ea-ba26-4ef9447da577",
"status": "INVALID",
"error": "Validation Failure",
"client_ref_num": "abcd123"
}

3.4 API Failure Response

In case of Failure, the response as explained in the Section 2.5 and error messages as defined
in the Section 2.5.1 Error Messages would be returned.

9
.5 Additional Notes

● API will be billable for any successful responses with http response code 200
irrespective of result code.

4 CKYC - Download API

4.1 API Introduction
This API helps to retrieve the complete CKYC details of an individual / legal entity. The
Download API accepts the CKYC ID and a particular auth factor responsible for identifying the
KYC end customer and returns complete details and list of documents submitted to financial
institutions in the past for KYC.

4.2 API Request

● Method: POST

● Header:

Key Mandatory/Optional Value

(M/O)

content-type M JSON/application

authorization M Type: Basic Auth, Username:client_id,

password:client_secret
/
BasicBase64encodedValueOf
(client_id:client_secret)

● Request Body:

Key Mandatory/ Value

Optional
(M/O)

client_ref_num M Unique ID for the OCR request from the Client side
[Max of 45 chars]

10
 ckyc_id M CKYC ID of the user (can be retrieved from CKYC
Search API)

auth_factor_type M Authentication Factor Type:

`DOB` - Date of Birth
`PIN_YOB` - PIN (6 digits) + Year of Birth (4 digits)
`MOBILE` - Mobile Number (10 digits)

auth_factor M Specific Authentication Factor based on type:

`DOB` - DD-MM-YYYY format
`PIN_YOB` - 10 digit [PIN (6 digits) + Year of Birth
(4 digits)]
`MOBILE` - 10 digit mobile number

4.3 API Success Response

4.3.1 Successful Validation (result_code 101) Case

When the CKYC ID and Auth Factor successfully matches and CKYC details are fetched,
similar response as below is expected:

{
"result_code":101,
"result":{
"personal_details":{
"constitution_type":"Individual",
"account_type":"Normal",
"ckyc_no":"40042297407249",
"prefix":"Mr",
"first_name":"Chidipotu",
"middle_name":"Sudharshan",
"last_name":null,
"full_name":"Mr Chidipotu Sudharshan",
"maiden_prefix":null,
"maiden_fname":null,
"maiden_mname":null,
"maiden_lname":null,
"maiden_fullname":null,
"father_or_spouse_flag":"Father",
"father_prefix":"Mr",
"father_fname":"Chidipotu",
"father_mname":"Prasad",
"father_lname":null,
"father_fullname":"Mr Chidipotu Prasad",
"mother_prefix":null,
"mother_fname":null,

11
 "mother_mname":null,
"mother_lname":null,
"mother_fullname":null,
"gender":"M",
"dob":"10-04-1996",
"pan":"BKHPC2392D",
"perm_line1":"SO Chidipotu Prasad18120402NAINAR SRINIVASA",
"perm_line2":"TOWERSRAMACHANDRA NAGARK T ROADNEAR
RAMACHANDRA",
"perm_line3":"MISSIONTirupati urbanChittoorAndhra
Pradesh517501",
"perm_city":"Chittoor",
"perm_dist":"Chittoor",
"perm_state":"Andhra Pradesh",
"perm_country":"IN",
"perm_pin":"517501",
"perm_poa":"Proof of Possession of Aadhaar",
"perm_corres_sameflag":"Y",
"corres_line1":"SO Chidipotu Prasad18120402NAINAR
SRINIVASA",
"corres_line2":"TOWERSRAMACHANDRA NAGARK T ROADNEAR
RAMACHANDRA",
"corres_line3":"MISSIONTirupati urbanChittoorAndhra
Pradesh517501",
"corres_city":"Chittoor",
"corres_dist":"Chittoor",
"corres_state":"Andhra Pradesh",
"corres_country":"IN",
"corres_pin":"517501",
"corres_poa":"01",
"resi_std_code":null,
"resi_tel_num":null,
"off_std_code":null,
"off_tel_num":null,
"mob_code":null,
"mob_num":null,
"email":null,
"remarks":null,
"dec_date":"16-07-2019",
"dec_place":"Bengaluru",
"kyc_date":"********",
"doc_sub":"04",
"kyc_name":"********",
"kyc_designation":"********",
"kyc_branch":"********",
"kyc_empcode":"********",
"org_name":"Krazybee Services Private limited",
"org_code":"IN2443",

12
 "num_identity":"2",
"num_related":"0",
"num_images":"2"
},
"identity_details":{
"identity":[
{
"sequence_no":"1",
"ident_type":"PAN",
"ident_num":"BKHPC2392D",
"idver_status":"N"
},
{
"sequence_no":"2",
"ident_type":"Proof Of Aadhaar",
"ident_num":"XXXXXXXX2162",
"idver_status":"N"
}
]
},
"related_person_details":null,
"image_details":{
"image":[
{
"sequence_no":"1",
"image_type":"jpg",
"image_code":"Proof of Possession of Aadhaar",
"global_flag":null,
"branch_code":"1389",
"image_data":"base64"
},
{
"sequence_no":"2",
"image_type":"jpg",
"image_code":"Photograph",
"global_flag":null,
"branch_code":"1389",
"image_data":"base64"
}
]
}
},
"status":"VALID",
"request_id":"5bd6b134-6ef9-40f5-8d9c-ff18982bfc6f",
"client_ref_num":"553",
"http_response_code":200
}

13
4.3.2 Unsuccessful Validation Case
The following response would be provided in case if the CKYC download API interrupts.

1. In case CKYC ID does not exist.

{
"error": "KYC Number 40042297407241 do not exists in system ",
"status": "INVALID",
"result_code": 103,
"request_id": "c40ca55e-6de2-4bba-ae6f-fa8b04157c37",
"client_ref_num": "979",
"http_response_code": 200
}

2. In case the auth factor is invalid.

{
"error": "Authentication Failed: Pincode and Year of birth entered does
not match with the CKYC Number 40042297407249",
"status": "INVALID",
"result_code": 103,
"request_id": "ac4b4c36-b99b-41ee-86a7-ed589d7774e8",
"client_ref_num": "278",
"http_response_code": 200
}

4.4 API Failure Response

In case of Failure, the response as explained in the Section 2.5 and error messages as defined
in the Section 2.5.1 Error Messages would be returned.

5 CKYC - Advanced API

5.1 API Introduction
CKYC - Advanced API is a combination of the search and download API features and helps to
retrieve the CKYC details of a user in a single flow. This API is very flexible and supports
numerous Government issued ID types and it helps to retrieve the complete CKYC details of an
individual / legal entity in a single flow. The API accepts the CKYC ID and a particular auth
factor responsible for identifying the KYC end customer and returns complete details and list of
documents submitted to financial institutions in the past for KYC.

14
5.2 API Request
● Method: POST

● Header:

Key Mandatory/Optional Value

(M/O)

content-type M JSON/application

authorization M Type: Basic Auth, Username:client_id,

password:client_secret
/
BasicBase64encodedValueOf
(client_id:client_secret)

● Request Body:

Key Mandatory/ Value

Optional
(M/O)

client_ref_num M Unique ID for the OCR request from the Client side
[Max of 45 chars]

ckyc_id M CKYC ID of the user (can be retrieved from CKYC

Search API)

identifier M Any Govt. issued ID (number)

identifier_type M Any Govt. issued ID (name) *refer to CKYC search

API

auth_factor_type M Authentication Factor Type:

`DOB` - Date of Birth
`PIN_YOB` - PIN (6 digits) + Year of Birth (4 digits)
`MOBILE` - Mobile Number (10 digits)

auth_factor M Specific Authentication Factor based on type:

`DOB` - DD-MM-YYYY format
`PIN_YOB` - 10 digit [PIN (6 digits) + Year of Birth
(4 digits)]
`MOBILE` - 10 digit mobile number

15
5.3 API Success Response

5.3.1 Successful Validation (result_code 101) Case

When the CKYC ID and Auth Factor successfully matches and CKYC details are fetched,
similar response as below is expected:

{
"result": 101,
"status": "VALID",
"search": {
"name": "MR CHAYAN DATTA",
"father_name": "Mr Prodyut Datta",
"age": "26",
"kyc_date": "11-04-2020",
"photo": "<base64>";
"remarks": null,
"ckyc_id": "10038682369602",
"photo_url":"<S3 Presigned URL>",
},
"download": {
"record_count_details": {
"download_count": "280",
"update_count": "0"
},
"personal_details": {
"constitution_type": "Individual",
"account_type": "Normal",
"ckyc_no": "10038682369602",
"prefix": "MR",
"first_name": "CHAYAN",
"middle_name": null,
"last_name": "DATTA",
"full_name": "MR CHAYAN DATTA",
"maiden_prefix": null,
"maiden_fname": null,
"maiden_mname": null,
"maiden_lname": null,
"maiden_fullname": null,
"father_or_spouse_flag": "Father",
"father_prefix": "Mr",
"father_fname": "Prodyut",
"father_mname": null,

16
 "father_lname": "Datta",
"father_fullname": "Mr Prodyut Datta",
"mother_prefix": "Mrs",
"mother_fname": "CHAITALI",
"mother_mname": null,
"mother_lname": "DATTA",
"mother_fullname": "Mrs CHAITALI DATTA",
"gender": "M",
"dob": "**-**-****",
"pan": "DQEPD*****",
"perm_line1": "S/O PRODYUT DATTA",
"perm_line2": "GEETANJALI APPARTMENT FLAT 407 CHAMPADALI
BARASAT",
"perm_line3": null,
"perm_city": "NORTH 24 PARGANAS",
"perm_dist": "North 24 Parganas",
"perm_state": "West Bengal",
"perm_country": "IN",
"perm_pin": "700124",
"perm_poa": "Proof of Possession of Aadhaar",
"perm_corres_sameflag": "Y",
"corres_line1": "S/O PRODYUT DATTA",
"corres_line2": "GEETANJALI APPARTMENT FLAT 407 CHAMPADALI
BARASAT",
"corres_line3": null,
"corres_city": "NORTH 24 PARGANAS",
"corres_dist": "North 24 Parganas",
"corres_state": "West Bengal",
"corres_country": "IN",
"corres_pin": "700124",
"corres_poa": null,
"resi_std_code": null,
"resi_tel_num": null,
"off_std_code": null,
"off_tel_num": null,
"mob_code": null,
"mob_num": "947744****",
"email": "CHAYAN*****@GMAIL.COM",
"remarks": null,
"dec_date": "08-04-2020",
"dec_place": "Bangalore",
"kyc_date": "********",
"doc_sub": "Certified",

17
 "kyc_name": "********",
"kyc_designation": "********",
"kyc_branch": "********",
"kyc_empcode": "********",
"org_name": "********",
"org_code": "********",
"num_identity": "0",
"num_related": "0",
"num_images": "4"
},
"identity_details": null,
"related_person_details": null,
"image_details": {
"image": [
{
"sequence_no": "1",
"image_type": "jpg",
"image_code": "Photograph",
"global_flag": "Global",
"branch_code": "BLR",
"image_data": "<base64>",
"image_url": "<S3 Presigned URL>"
},
{
"sequence_no": "2",
"image_type": "pdf",
"image_code": "PAN",
"global_flag": "Global",
"branch_code": "BLR",
"image_data": "<base64>",
"image_url": "<S3 Presigned URL>"
},
{
"sequence_no": "3",
"image_type": "jpg",
"image_code": "Proof of Possession of Aadhaar",
"global_flag": "Global",
"branch_code": "BLR",
"image_data": "<base64>",
"image_url": "<S3 Presigned URL>"
},
{
"sequence_no": "4",

18
 "image_type": "jpg",
"image_code": "Signature",
"global_flag": "Global",
"branch_code": "BLR",
"image_data": "<base64>",
"image_url": "<S3 Presigned URL>"
}
]
}
},
"request_id": "a6c86c75-5bcc-4fee-9678-fbfbd6983b9c",
"client_ref_num": "931",
"http_response_code": 200
}

5.3.2 Partial Validation

The following response would be provided in case if the CKYC search was successful and
download was interrupted.
{
"result": 105,
"status": "PARTIALLY_VALID",
"search": {
"name": "MR CHAYAN DATTA",
"father_name": "Mr Prodyut Datta",
"age": "26",
"kyc_date": "11-04-2020",
"photo": "<base64>"
"remarks": null,
"ckyc_id": "10038682369602",
"photo_url": "<S3 Presigned URL>"
},
"download": {
"error": "Authentication Failed: Date of birth entered does not
match with the date of birth stated in the CKYC number 10038682369602"
},
"request_id": "43ef8fef-5141-445c-be30-6adefd19ceee",
"client_ref_num": "554",
"http_response_code": 200
}

19
5.3.3 Unsuccessful Validation Case
The following response would be provided in case if no records are found.

{
"error": "No record found",
"status": "INVALID",
"result_code": 103,
"request_id": "b166c697-4546-4d18-a8ff-45026184e986",
"client_ref_num": "722",
"http_response_code": 200
}

5.4 API Failure Response

In case of Failure, the response as explained in the Section 2.5 and error messages as defined
in the Section 2.5.1 Error Messages would be returned.

5.5 Additional Notes

● API will be billable for any successful responses with http response code 200
irrespective of result code.

----------------------------------- End of Document -----------------------------------------

20