Version History:

Version	Description	Author	Date (dd/mm/yyyy)
1.0.0	DRAP eKYC Journey [EFR] Document	Ajai Antony	07/06/2024
1.0.1	Update on various model description and sequence diagram	Ajai Antony	28/08/2024
1.0.2	New error code (45004) included under Confirm Identity (API 5)	Ajai Antony	29/08/2024
1.0.3	Included AML CallBack API	Ajai Antony	15/10/2024
1.0.4	Web HTML Model deprecated & removed	Ajai Antony	20/02/2025

CLASSIFICATION: PUBLIC

These APIs are used to onboard a customer via e-KYC by authorized entities associated with Lulu.

EFR as the provider has multiple options to complete an EKYC.

Web SDK Model
Mobile SDK Model

Web SDK Model

With this model, Partner will send an EKYC request to CDP and the partner initiate the EFR SDKs. EFR SDK will take care of OCR and Face liveness.

EFR WEB SDK and EFR WEB SDK integration sample project:

https://drive.google.com/file/d/14vquYOenwLFjcSJ2-XmVqPxgZ3QUSTea/view?usp=sharing

Mobile SDK Model

With this model, Partner will send an EKYC request to CDP and the partner initiate the EFR SDKs. EFR SDK will take care of OCR and Face liveness.

EFR Development Kit - Android & IOS:

https://drive.google.com/file/d/11XvjE-sFBBlFVjuwZUIMLdBKyjJhW0em/view?usp=drive_link

APIs

Access token API (API 1)

An access token is the key to the gateway to access any other API. The API will return the access token if the user is successfully authenticated and has authorization to access these services. Every access token is tagged with validity, and the expiry duration is echoed in the response for the calling application to manage the state accordingly. A token that is used after its validity period will restrict access to any services, and a new token will be generated in this case.

API	https://{{baseUrl}}/auth/realms/cdp/protocol/openid-connect/token
Method	POST
Headers	Content-Type : application/x-www-form-urlencoded
Access Token Payload	`--data-urlencode 'grant_type=password' \ --data-urlencode 'scope=api://3a3f52a1-1b64-4c27-81f0-50a6ca01324d/customer' \ --data-urlencode 'client_id=<<client_id>>' \ --data-urlencode 'client_secret=<<secret>>' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'username=<<username>>' \ --data-urlencode 'password=<<password>>'`
Refresh Token Payload	`--data-urlencode 'grant_type=password' \ --data-urlencode 'client_id=<<client_id>>' \ --data-urlencode 'client_secret=<<secret>>' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'refresh_token=<<refreshToken>>' \`
Response	`{ "token_type": "bearer", "access_token": "<<access_token_value>>", "expires_in": 7199, "refresh_expires_in": 7199, "refresh_token": "<<refresh_token_value>>", "scope": "----", "not-before-policy": 0, "session_state": "<<session_state>>" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	mandatory	Content type

Payload

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
grant_type	String	10	mandatory	Grant type. Will up provided
scope	String	60	CONDITIONAL	Scope name. Will be provided
client_id	String	60	mandatory	Client Id. Will be provided
client_secret	String	60	mandatory	Client secret. Will be provided
username	String	60	mandatory	Admin user name
password	String	60	mandatory	Admin password

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
token_type	String	-	Token type
scope	String	-	Scope details
access_token	String	600	Access token to access the APIs
refresh_token	String	600	refresh token to refresh the Token.
expires_in	Integer	-	Token expiry time in seconds
refresh_expires_in	Integer	-	Refresh Token expiry time in seconds

Request e-KYC ( API 2)

This API is used to create an e-KYC request in order to use the e-KYC, and it will check whether the requester has the authorization to use the provided e-KYC solution.

The Request e-KYC API will provide a success result with a unique e-KYC Request Id and encrypted HTML page content or SDK configuration data based on the e-KYC provider and e-KYC model.

API	https://{{baseUrl}}/ekyc/api/v1/request
Authorization	Bearer Token
Method	POST
Headers	Content-Type:application/json
Payload	`{ "channel": "WEB", "ekyc_provider": "EFR", "ekyc_model": "WEB", "ecrn": "<<ecrn>>", "primary_mobile_number": "<<customer_mobile>>", "email_id": "<<customer_email_id>>" }`
Success Response for WEB model Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "ekyc_request_id": "4e41d40a-6f16-4874-977b-017798d1e583", "ekyc_request_data": { "ekyc_portal_html": "<<encrypted_base_64_ekyc_portal_html_if_any>>" } } }`
Success Response for SDK model Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "ekyc_request_id": "ab7562a0-e4c8-4873-8160-ae701b10eb3c", "ekyc_request_data": { "ekyc_sdk_configuration": "<<ekyc sdk configuration>>", "ekyc_sdk_secretKey": { "code": 281419905, "value": "bkZjS4KYaHWoFdMKOB73enCsU1HiiRlwM1y1nnN6WHQRY5g3g3J17rJKAWUnGNOGh+LGDUU3dXN0KILvkN1c/w==", "expiry": "2023-03-08 14:00:00" } } } }`
Bad Request Http status Code:200	`{ "status": "failure", "statusCode": 400, "errorCode": 400, "message": "Invalid primaryMobileNumber,ekycProvider is mandatory,channel is mandatory" }`
Failure Response e-KYC not Configured Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46001, "message": "eKYC not Configured for the Agent!" }`
Failure Response Invalid e-KYC Provider Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46002, "message": "Invalid eKYC Provider" }`
Failure Response Invalid e-KYC Model for e-KYC Provide Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46003, "message": "Invalid eKYC Model for eKYC Provider!" }`
Authentication Failure Http status Code :401	`{ "timestamp": "2022-12-05T13:44:31.557+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/request" }`
Partner (e-KYC Provider)Service Failure Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47001, "message": "EFR eKYC Service is Down!" }` `{ "status": "failure", "statusCode": 500, "errorCode": 47002, "message": "EFR Web Portal is Down!" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	mandatory	Content type
Authorization	String		mandatory	Authorization Token

Payload

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
channel	String	20	mandatory	Channel
ekyc_provider / ekycProvider	String	30	mandatory	EKYC Provider
ekyc_model / ekycModel	String	30	mandatory	EKYC Model: WEB / FACE_WEB / SDK
ecrn	String	255	CONDITIONAL	CDP customer unique identification Number, provide only for existing CDP customer.
primary_mobile_number PrimaryMobileNumber	String	20	CONDITIONAL	Primary Mobile Number
email_id / emailId	String	120	CONDITIONAL	Email ID

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
status	String	255	status description
status_code	Int	-	Status code
message	String	255	Message
data	Object	-	Data object
ekyc_request_id	String	50	e-KYC Request unique identification number
ekyc_request_data	Object	-	Data object
ekyc_portal_html	String	4000	Base64 encrypted e-KYC Portal HTML content only for the WEB e-KYC model.
ekyc_sdk_configuration	String	4000	e-KYC SDK Configuration Data only for the SDK e-KYC model.
ekyc_sdk_secretKey	Object		e-KYC SDK Secret Key data is only for the SDK e-KYC model.

OCR Analyze ( API 3)

OCR Detection API accepts the ID Document front and back and provides the contents of the ID Document.

API	https://{{baseUrl}}/ekyc/api/v1/efr/ocrDetection
Authorization	none
Method	POST
Headers	Content-Type:application/json
Payload	`{ "ekycRequestId": "<<ekycRequestId>>", "document": "<<id_document_front_base64>>", "documentBack": "<<id_document_back_base64>>" }`
Success Response Http status Code :200	{ "status": "string", "statusCode": 0, "errorCode": 0, "message": "string", "data": { "success": true, "transactionId": "string", "identityCard": { "frontCardScan": "string", "backCardScan": "string", "mrz": { "line1": "string", "line2": "string", "line3": "string" }, "details": { "docCode": "string", "docIssuingAuthority": "string", "docNumber": "string", "docExpiryDate": "string", "docExpiryDateShort": "string", "primaryIdentifier": "string", "secondaryIdentifiers": "string", "dateOfBirth": "string", "gender": "string", "nationality": "string", "registrantNumber": "string" } }, "documentIdentifiers": [ { "docCode": "string", "docIssuingAuthority": "string", "docNumber": "string", "expiryDate": "string" } ] } }
Authentication Failure Http status Code :401	`{ "timestamp": "2022-12-05T13:44:31.557+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/request" }`
Bad Request Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 400, "message": "ekycRequestId is mandatory" }`
e-KYC Request Id not found (Not found) Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46004, "message": "eKYC RequestId not found!" }`
e-KYC Provider Mismatch (Bad Request) Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 46005, "message": "eKYC Request associated with different eKYC Provider!" }`
e-KYC Request Expired (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46006, "message": "eKYC Request Expired!" }`
e-KYC Request already Failed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46007, "message": "eKYC Failed, Initiate new Request!" }`
e-KYC Request already Rejected (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46008, "message": "eKYC Rejected, Initiate new Request!" }`
e-KYC Request already Completed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46009, "message": "eKYC already Completed!" }`
Partner (e-KYC Provider)Service Failure Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47001, "message": "EFR eKYC Service is Down!" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	Mandatory	Content type

Payload

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
ekycRequestId	String	54000	Mandatory	EKYC Request unique identification number
document	String		Mandatory	ID Document Front base 64 data
documentBack	String		Mandatory	ID Document Back base 64 data

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
status	String	255	status description
status_code	Integer	-	Status code
message	String	255	Message
data	Object	-	Data object
success	Boolean		OCR Detection status
transactionId	String		Unique OCR Detection ID
identityCard	Object	255	ID Card Details
frontCardScan	String	4000	ID Document Front base 64 data
backCardScan	String	4000	ID Document Back base 64 data
mrz	Object	-	MRZ line Details in the ID Document
line1	String	255	MRZ Line 1
line2	String	255	MRZ Line 2
line3	String	255	MRZ Line 3
details	Object		ID Card Document Details
docCode	String	255	ID Document Unique Identification
docIssuingAuthority	String	255	ID Document Issuing Authority
docNumber	String	255	ID Document Number
docExpiryDate	String	255	ID Document Expiry Date
docExpiryDateShort	String	255	ID Document Expiry Date short
primaryIdentifier	String	255	ID Document Primary Identifier
secondaryIdentifiers	String	255	ID Document Secondary Identifier
dateOfBirth	String	255	ID Document Date of Birth
gender	String	255	Gender
nationality	String	255	Nationality
registrantNumber	Stringeger	255	ID Document Registration Number
documentIdentifiers	Object		Document Identifier
docCode	String	255	Document Identification Code
dosccIssuingAuhortys	Boolean		IDDocmnIssgAthoityOCR Detection status
dotNmbanacionIr	SringString		ID ocumenNumrUnique OCR Detection ID
idexinyDiteyCard	Object	255	IDDocumentxpiDID Card Details
frontCardScan	String	4000	ID Document Front base 64 data
backCardScan	String	4000	ID Document Back base 64 data
mrz	Object	-	MRZ line Details in the ID Document
line1	String	255	MRZ Line 1
line2	String	255	MRZ Line 2
line3	String	255	MRZ Line 3
details	Object		ID Card Document Details
docCode	String	255	ID Document Unique Identification
docIssuingAuthority	String	255	ID Document Issuing Authority
docNumber	String	255	ID Document Number
docExpiryDate	String	255	ID Document Expiry Date
docExpiryDateShort	String	255	ID Document Expiry Date short
primaryIdentifier	String	255	ID Document Primary Identifier
secondaryIdentifiers	String	255	ID Document Secondary Identifier
dateOfBirth	String	255	ID Document Date of Birth
gender	String	255	Gender
nationality	String	255	Nationality
registrantNumber	String	255	ID Document Registration Number
documentIdentifiers	Object		Document Identifier
docCode	String	255	Document Identification Code
docIssuingAuthority	String	255	ID Document Issuing Authority
docNumber	String	255	ID Document Number
expiryDate	String	255	ID Document Expiry Date

Face Liveness (API 4)

Face Liveness API is used to check the face liveness of the customer.

API	https://{{baseUrl}}/ekyc/api/v1/efr/faceLiveness
Authorization	None
Method	POST
Headers	Content-Type:application/json
Payload	`{ "ekycRequestId": "<<ekycRequestId>>", "data": "<<face_data_from_sdk>>" }`
Success Response Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "data": "<<encrypted_face_data_response>>" } }`
Authentication Failure Http status Code :401	`{ "timestamp": "2022-12-05T13:44:31.557+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/request" }`
Bad Request Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 400, "message": "ekycRequestId is mandatory" }`
e-KYC Request Id not found (Not found) Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46004, "message": "eKYC RequestId not found!" }`
e-KYC Provider Mismatch (Bad Request) Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 46005, "message": "eKYC Request associated with different eKYC Provider!" }`
e-KYC Request Expired (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46006, "message": "eKYC Request Expired!" }`
e-KYC Request already Failed (Internal Server Error)	`{ "status": "failure", "statusCode": 500, "errorCode": 46007, "message": "eKYC Failed, Initiate new Request!" }`
e-KYC Request already Rejected (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46008, "message": "eKYC Rejected, Initiate new Request!" }`
e-KYC Request already Completed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46009, "message": "eKYC already Completed!" }`
Partner (e-KYC Provider)Service Failure Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47001, "message": "EFR eKYC Service is Down!" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	mandatory	Content type

Payload

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
ekycRequestId	String	50	mandatory	EKYC Request unique identification number
data	String	4000	mandatory	face data got from sdk

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
status	String	255	status description
status_code	Int	-	Status code
message	String	255	Message
data	Object	-	Data object
data	String	4000	Encrypted face data response

Confirm Identity (API 5)

The customer's identity is verified using the confirm identity API. The ID document will be validated, and the captured face will be compared to the ID document face.

After the identity has been verified, it will check the initiating agent's e-KYC configuration to see if more data is required to finish e-KYC.

The customer will be onboarded to the customer data platform if additional information is not needed.

API	https://{{baseUrl}}/ekyc/api/v1/efr/confirmIdentity
Authorization	None
Method	POST
Headers	Content-Type:application/json
Payload	{ "ekycRequestId": "<<ekycRequestId>>", "face": { "data": "<<face_date>>", "datahash": "Kn3lxsnxI1mFfYV97W6cdYquC0YBDHCeFSYEfoqDk7o=", "thumbnail": "<<face_thumbnaile_base64_data>>", "tag": "EFR.2008756088" }, "identityCard": { "frontCardScan": "<<id_card_front_base64>>", "backCardScan": "<<id_card_back_base64>>", "mrz": { "line1": "ILARE1070175548784199554586091", "line2": "9507281M2308027IPD4<<<<1<<<<<1", "line3": "MUNDACHI<<IRFAN<MANAKKAT<THEKK" }, "details": { "docCode": "IL", "docIssuingAuthority": "ARE", "docNumber": "107017554", "docExpiryDate": "2023-08-02", "docExpiryDateShort": "230802", "primaryIdentifier": "irfan", "secondaryIdentifiers": "Thekke", "dateOfBirth": "950728", "gender": "M", "nationality": "ARE", "registrantNumber": "784199554586091" } }, "documentIdentifiers": [ { "docCode": "IL", "docIssuingAuthority": "ARE", "docNumber": "107017554" } ] }
Success Response if there is no other pending task (ex:- additional information) Customer Onboarded to CDP Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "confirmation_status": true, "ecrn": "1058021235161541", "customer_status": "ACTIVE", "aml_scan_status": "Accepted" } }`
Success Response if there is pending Task - Customer not onboarded to CDP Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "confirmation_status": true } }`
Success Response for Identity Mismatch if there is pending Task - Customer not onboarded to CDP Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "confirmation_status": false, "rejection_message" :"<<failure message>>" } }`
Authentication Failure Http status Code :401	`{ "timestamp": "2022-12-05T13:44:31.557+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/request" }`
e-KYC Request Id not found (Not found) Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46004, "message": "eKYC RequestId not found!" }`
e-KYC Provider Mismatch (Bad Request) Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 46005, "message": "eKYC Request associated with different eKYC Provider!" }`
e-KYC Request Expired (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46006, "message": "eKYC Request Expired!" }`
e-KYC Request already Failed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46007, "message": "eKYC Failed, Initiate new Request!" }`
e-KYC Request already Rejected (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46008, "message": "eKYC Rejected, Initiate new Request!" }`
e-KYC Request already Completed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46009, "message": "eKYC already Completed!" }`
Partner (e-KYC Provider)Service Failure Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47001, "message": "EFR eKYC Service is Down!" }`
Validation Failure Response - Customer Under Compliance Investigation HttpStatusCode : 200	`{ "status": "failure", "statusCode": 500, "errorCode": 45013, "message": "Customer under Compliance investigation!" }`
Validation Failure Response - Blocked Customer HttpStatusCode : 200	`{ "status": "failure", "statusCode": 404, "errorCode": 45051, "message": "Customer can not be Accepted" }`
Customer Onboarding Failed HttpStatusCode : 200	`{ "status": "failure", "statusCode": 500, "errorCode": 47006, "message": "Customer onboarding failed!" }`
Customer not Residing in the country HttpStatusCode : 200	`{ "status": "failure", "statusCode": 500, "errorCode": 45004, "message": "Customer is currently not in the country!"" }`
CDP Service is Down Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47006, "message": "CDP Service is Down!" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	mandatory	Content type

Payload

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
ekycRequestId	String	50	mandatory	EKYC Request unique identification number
face	Object		mandatory	face Details
data	String	4000	mandatory	face data
dataHash	String		mandatory	data Hash
tag	String		mandatory	tag
thumbnail	String	4000	CONDITIONAL	thumbnail portrait of the face captured
identityCard	Object		mandatory	ID Card Details
frontCardScan	String	4000	mandatory	ID Document Front base 64 data
backCardScan	String	4000	mandatory	ID Document Back base 64 data
mrz	Object	-	CONDITIONAL	MRZ line Details in the ID Document
line1	String	255	CONDITIONAL	MRZ Line 1
line2	String	255	CONDITIONAL	MRZ Line 2
line3	String	255	CONDITIONAL	MRZ Line 3
details			mandatory	ID Card Document Details
docCode	String	255	mandatory	ID Document Unique Identification
docIssuingAuthority	String	255	mandatory	ID Document Issuing Authority
docNumber	String	255	mandatory	ID Document Number
docExpiryDate	String	255	mandatory	ID Document Expiry Date
docExpiryDateShort	String	255	mandatory	ID Document Expiry Date short
primaryIdentifier	String	255	mandatory	ID Document Primary Identifier
secondaryIdentifiers	String	255	mandatory	ID Document Secondary Identifier
dateOfBirth	String	255	mandatory	ID Document Date of Birth
gender	String	255	mandatory	Gender
nationality	String	255	mandatory	Nationality
registrantNumber	String	255	mandatory	ID Document Registration Number
documentIdentifiers	Object		mandatory	Document Identifier
docCode	String	255	mandatory	ID Document Issuing Authority
docIssuingAuthority	String	255	mandatory	ID Document Issuing Authority
docNumber	String	255	mandatory	ID Document Number
expiryDate	String	255	mandatory	ID Document Expiry Date

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
status	String	255	status description
status_code	Int	-	Status code
message	String	255	Message
data	Object	-	Data object
confirmation_status	Boolean	-	e-KYC Confirmation Status
ecrn (conditional)	String	20	CDP Customer Unique Identification Number will be present if customer is onboarded to CDP
aml_scan_status (conditional)	String	20	AML Scanned Status will be p[resent if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done)
customer_status (conditional)	String	20	Customer Status will be present if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED
rejection_message (conditional)	String	500	rejection message will be there if the confirmation status is false

Provide Additional Information (API 6)

This API is used to provide the customer additional information in order to complete e-KYC, and the customer will be onboarded to CDP if there are no other pending tasks.

API	https://{{baseUrl}}/ekyc/api/v1/additionalInformation/{{ekycRequestId}}
Authorization	Bearer Token
Method	POST
Headers	Content-Type:application/json
Payload	{ "salutation": "Mr.", "preferred_name": "Irfan", "second_nationality": "GB", "native_region": 1, "date_of_birth": "19995-03-08", "country_of_birth": "IN", "place_of_birth": "Kannur", "gender": "Male", "mothers_maiden_name": "Safiya", "primary_mobile_number": "+971502106707", "secondary_mobile_number": "+971520210458", "email_id": "irfanmtp1@gmail.com", "occupation_id": 10, "updated_by": "userAbc", "customer_classification": { "customer_type_id": 1, "annual_income_range_id": 5, "annual_income_currency_code": "AED", "social_security_number": "SSN123", "tax_registration_umber": 1234567, "txn_issued_country": "AE", "employer_name": "Lulu International Exchange", "employer_address": "Dubai", "employer_phone": "+971502106707", "employer_ecrn": "123456789", "employer_establishment_id": "30000120", "group_companies": 1, "group_employer_code": "786000777", "personal_mohre_id": "Mohre123", "income_type": 3, "profession_category": "PC1", "reason_for_acc": "Test", "referred_by_type": 4, "referred_by": "Irfan", "txn_vol_month": 2, "txn_count_month": 2, "customer_remarks": "test remark", "show_remarks_on_txn": true, "agent_ref_no": "ABC1234582", "first_language": "en", "marital_status": 1 }, "address_list": [ { "address_type_id": "1", "building_name": "ABC Building", "street_name": "Electra Street", "landmark": "Landmark", "city": "DUBAI", "district": "DUBAI", "state": "DUBAI", "country": "AE", "zip": null, "po_box": "5379", "mobile_number": null, "email_id": null } ] }
Success Response Http status Code :200	`{ "status": "success", "statusCode": 200, "data": { "ecrn": "1058021235161541", "customer_status": "ACTIVE", "aml_scan_status": "Accepted" } }`
Authentication Failure Http status Code :401	`{ "timestamp": "2022-12-05T13:44:31.557+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/request" }`
Bad Request Http status Code :200	`{ "status": "failure", "statusCode": 400, "errorCode": 46022, "message": " emailId is mandatory in request !" }`
e-KYC Request Id not found (Not found) Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 46004, "message": "eKYC RequestId not found!" }`
e-KYC Request Expired (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46006, "message": "eKYC Request Expired!" }`
e-KYC Request already Failed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46007, "message": "eKYC Failed, Initiate new Request!" }`
e-KYC Request already Rejected (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46008, "message": "eKYC Rejected, Initiate new Request!" }`
e-KYC Request already Completed (Internal Server Error) Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 46009, "message": "eKYC already Completed!" }`
Validation Failure Response - Customer Under Compliance Investigation HttpStatusCode : 200	`{ "status": "failure", "statusCode": 500, "errorCode": 45013, "message": "Customer under Compliance investigation!" }`
Validation Failure Response - Blocked Customer HttpStatusCode : 200	`{ "status": "failure", "statusCode": 404, "errorCode": 45051, "message": "Customer can not be Accepted" }`
Customer onboarding failed HttpStatusCode : 200	`{ "status": "failure", "statusCode": 500, "errorCode": 47006, "message": "Customer onboarding failed!" }`
CDP Service is Down Http status Code :200	`{ "status": "failure", "statusCode": 500, "errorCode": 47006, "message": "CDP Service is Down!" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	mandatory	Content type
Authorization	String		mandatory	Authorization Token

Payload

Mandatory fields may vary based on the e-KYC Provider and agent.

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
updated_by	String	255	Updated User Id
salutation	String	3	Salutation(Mr, Ms) , Salutation Id As per SALUTATION master
preferred_name	String	60	Preferred Name
second_nationality	String	2	Second Nationality code of Customer as per NATIONALITY Master
native_region	Integer		Native Region code asper NATIVE_REGION Master
date_of_birth	Date		Date of Birth in “YYYY-MM-DD” Format
country_of_birth	String	2	Country of Birth code as per COUNTRY Master
place_of_birth	String	40	Place of Birth
resident_type_id	Long		Resident Type Id as per RESIDENT_TYPE Master
country_of_residence	String	2	Resident Country code as per COUNTRY master
gender	String	12	Gender : Male/Female/Other
mothers_maiden_name	String	30	Mothers Name
primary_mobile_number	String	20	Primary Mobile Number
secondary_mobile_number	String	20	Secondary Mobile Number
email_id	String	254	Email Id
phone_number	String	20	Phone Number
occupation_id	Long		Occupation Id as per OCCUPATION master
addressList	Object		Data Object
address_type_id	Long		Address Type Id as per ADDRESS_TYPE master
building_name	String	30	Building Name
street_name	String	30	Street Name
landmark	String	30	Landmark
country	String	2	Country
state	String	30	State
district	String	30	District
city	String	30	City
zip	Long		Zip
mobile_number	String	30	Mobile Number
status	String	30	Disable
customer_classification	Object		Data Object
customer_type_id	Long		Customer Type Id as per CUSTOMER_TYPE master
income_type			Income type id as per INCOME_TYPE master
annual_income_range_id	Long		Annual Income Range Id As per ANNUAL_INCOME master
annual_income_currency_code	String	30	Annual Income Currency Code as per CURRENCY master
social_security_number	String	30	Social Security Number
tax_registration_number	Long		Tax Registration Number
txn_issued_country	String	2	Tax Issued Country code as per COUNTRY master
employer_name	String	30	Employer Name
employer_address	String	30	Employer Address
employer_phone	String	30	Employer Phone
employer_ecrn	String	30	Employer ECRN
employer_establishment_id	String	30	Employer Establishment ID
risk_rating_id	Long		Risk Rating ID as per RISK_RATING master
compliance_category_id	Long		Compliance Category ID
group_companies	Integer		Group Company id as per GROUP_COMPANY master
group_employer_code	String	30	Group Employee Code
personal_mohre_id	String	30	Personal Mohre Id
customer_cards	String	30	Customer Cards
card_number	String	30	Card Number
profession_category	String	30	Profession Category
reason_for_acc	String	30	Reason for ACC
referred_by_type	Integer		Referred By Type
referred_by	String	30	Reffered By
txn_vol_month	String	30	Transaction Volume Month
txn_count_month	String	30	Transaction Count Month
show_remarks_on_txn	Boolean		show Remarks on transaction
customer_remarks	String	30	Remarks on Transaction
agent_ref_no	String	30	Agent reference number
first_language	String	3	Customer Preferred Language
marital_status	Integer		Marital Status
profile_category	Integer		Profile Category
dnfbp	Boolean		Designated Non-Financial Business and Professions

Parameter

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
ekycRequestId	String	50	MANDATORY	e-KYC Request Id

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
status	String	255	status description
status_code	Int	-	Status code
data	Object	-	Data object
ecrn (conditional)	String	20	CDP Customer Unique Identification Number if customer is onboarded to CDP
aml_scan_status (conditional)	String	20	AML Scanned Status if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done)
customer_status (conditional)	String	20	Customer Status if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED

Get Customer Profile (API 7)

API to be used to get the customer information by customer number.

API	https://{{baseUrl}}/caas/api/v2/customer/{{ecrn}}
Authorization	Bearer Token
Method	GET
Headers	Content-Type:application/json
Payload	`None`
Success Response Http status Code :200	{ "ecrn": "1058021235161541", "first_name": "IRFAN MANAKKAT THEKKE", "salutation": null, "middle_name": "PURAYIL ISMAIL", "last_name": "NANGARATH MUNDACHI", "preferred_name": "IRFAN MANAKKAT THEKKE", "nationality": "IN", "second_nationality": "GB", "native_region": 1, "date_of_birth": "1995-07-28", "country_of_birth": "IN", "place_of_birth": "INDIA", "resident_type_id": 101, "country_of_residence": "AE", "gender": "Male", "mothers_maiden_name": "maiden Name", "primary_mobile_number": "+971502106707", "secondary_mobile_number": "+971502106706", "email_id": "irfanmtp1@gmail.com", "phone_number": "+971502106705", "occupation_id": 2856, "political_exposed_person": false, "aml_scan_status": "Accepted", "customer_iban": "AE083141058021235161541", "customer_status": "ACTIVE", "aml_category": 5, "additional_docs": [ { "contentType": "image/jpeg", "file_name": "customer/additionalDoc/1058021235161541_1.jpeg" } ], "address_list": [ { "dateUpdated": "2023-03-15T14:34:07.849554Z", "address_type_id": "1", "building_name": "MANKHOOL BUILDING", "street_name": "", "landmark": "AL NAHDA", "city": "EMIRATE OF DUBAI", "district": "", "state": " ", "country": "AE", "zip": 0, "mobile_number": null } ], "id_details": [ { "dateUpdated": "2023-03-15T14:34:07.849554Z", "id_type": 2, "id_number": "P4006315", "visa_number": "0", "visa_expiry_date": null, "name_as_per_id": " ", "issued_country": "IN", "issued_by": "INDIA Govt.", "issued_at": null, "issued_on": "2016-08-08", "date_of_expiry": "2026-08-08", "default_status": true, "active_status": true, "id_front": null, "id_back": null }, { "dateUpdated": "2023-03-15T14:34:07.849554Z", "id_type": 4, "id_number": "784199554586091", "visa_number": "0", "visa_expiry_date": null, "name_as_per_id": " ", "issued_country": "AE", "issued_by": "EIDA", "issued_at": null, "issued_on": "2020-08-08", "date_of_expiry": "2023-08-08", "default_status": true, "active_status": true, "id_front": { "base64_data": "", "file_name": "customer/id/1058021235161541_ID_FR_4_784199554586091.jpeg", "content_type": "image/jpeg" }, "id_back": null } ], "customer_classification": { "dateUpdated": "2023-02-14T10:28:03.762012Z", "customer_type_id": 2, "annual_income_range_id": 15, "annual_income_currency_code": null, "social_security_number": null, "tax_registration_number": null, "txn_issued_country": null, "employer_name": "EMKE", "employer_address": "UAE", "employer_phone": " ", "employer_ecrn": "", "employer_establishment_id": "", "risk_rating_id": 3, "last_review_date": null, "next_review_date": null, "pep_category": null, "group_companies": null, "group_employer_code": " ", "personal_mohre_id": "", "income_type": 1, "profession_category": "", "reason_for_acc": " ", "referred_by": "1058021235161541", "referred_by_type": 1, "txn_vol_month": 1, "txn_count_month": 1, "show_remarks_on_txn": false, "customer_remarks": "", "agent_ref_no": null, "ekyc_provider": null, "ekyc_ref_no": null, "customer_cards": null, "card_number": null, "social_links": [], "subscriptions": [ { "subsciption_type": "PREMIUM", "subscription_id": "GOLD CARD", "status": "active" } ], "first_language": "", "marital_status": null, "dnfbp": false, "dpms": false, "profile_category": 1, "profile_photo_file_name": null }, "customer_relations": [], "communication_consents": [ { "allow": true, "communication_type": 1 }, { "allow": true, "communication_type": 2 } ] }
Customer not found Failure Response Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 45001, "message": "Customer not found" }`
Customer Not Subscribed Failure Response Http status Code :200	`{ "status": "failure", "statusCode": 404, "errorCode": 45003, "message": "Customer not Subscribed" }`
Authentication Failure Response Http status Code :401	`{ "timestamp": "2023-03-15T14:26:24.292+00:00", "status": 401, "error": "Unauthorized", "message": "", "path": "/api/v1/customer/7841001228796988" }`

Header

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
Content-Type	String	36	MANDATORY	Content type
Authorization	String		MANDATORY	Authorization Token

Parameter

Name	Data Type	Max Length	Mandatory	Description

Name	Data Type	Max Length	Mandatory	Description
ecrn	String	20	MANDATORY	Customer unique identification number

Response

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
agent_location_id	String	30	Agent Location Id
channel	String	30	Channel
salutation	String	3	Salutation(Mr, Ms)
first_name	String	30	First Name
middle_name	String	30	Middle Name
last_name	String	30	Last Name
preferred_name	String	30	Preferred Name
nationality	String	2	Nationality
second_nationality	String	2	Second Nationality of Customer
native_region	Integer		Native Region
date_of_birth	Date		Date of Birth
country_of_birth	String	2	Country of Birth
place_of_birth	String	100	Place of Birth
resident_type_id	Long		Resident Type Id
country_of_residence	String	2	Country of Residence
gender	Male	12	Gender
mothers_maiden_name	String	30	Mothers Name
primary_mobile_number	String	30	Primary Mobile Number
secondary_mobile_number	String	30	Secondary Mobile Number
email_id	String	30	Email Id
phone_number	String	30	Phone Number
occupation_id	Long		Occupation Id
political_exposed_person	Boolean		Political Exposed Person
additional_docs	Object		Data Object
idNameId	String		Id name id
base64_data	String
content_type	String		Content Type
id_details	Object		Data Object
id_type	Long		Id Type
id_number	String	30	Id Number
name_as_per_id	String	30	Name as per Id
issued_country	String	2	Issued Country
issued_by	String	30	Issued By
issued_at	String	30	Issued At
issued_on	Date		Issued On
date_of_expiry	Date		Date of Expiry
visa_number	String	30	Visa Number
visa_expiry_date	Date		Visa Expiry Date
default_status	String	30	Default Status
active_status	String	30	Active Status
id_front	Object		Data Object
base64_data	String		Base 64 Data
content_type	String		Content Type
id_back	Object		Data Object
base64_data	String		Base 64 Data
content_type	String		Content Type
addressList	Object		Data Object
address_type_id	Long		Address Type Id
building_name	String	30	Building Name
street_name	String	30	Street Name
landmark	String	30	Landmark
country	String	2	Country
state	String	30	State
district	String	30	District
city	String	30	City
zip	Long		Zip
mobile_number	String	30	Mobile Number
status	String	30	Disable
customer_classification	Object		Data Object
customer_type_id	Long		Customer Type Id
annual_income_range_id	Long		Annual Income Range
annual_income_currency_code	String	30	Annual Income Currency Code
social_security_number	String	30	Social Security Number
tax_registration_number	Long		Tax Registration Number
txn_issued_country	String	2	Tax Issued Country
employer_name	String	30	Employer Name
employer_address	String	30	Employer Address
employer_phone	String	30	Employer Phone
employer_ecrn	String	30	Employer ECRN
employer_establishment_id	String	30	Employer Establishment ID
risk_rating_id	Long		Risk Rating ID
compliance_category_id	Long		Compliance Category ID
last_review_date	Date		Last review Date
next_review_date	Date		Next Review Date
pep_category	Integer		Pep Category
group_companies	Integer		Group Company
group_employer_code	String	30	Group Employee Code
personal_mohre_id	String	30	Personal Mohre Id
customer_cards	String	30	Customer Cards
card_number	String	30	Card Number
income_type	String	30	Income Type
profession_category	String	30	Profession Category
reason_for_acc	String	30	Reason for ACC
referred_by_type	Integer		Referred By Type
referred_by	String	30	Reffered By
txn_vol_month	String	30	Transaction Volume Month
txn_count_month	String	30	Transaction Count Month
show_remarks_on_txn	Boolean		show Remarks on transaction
customer_remarks	String	30	Remarks on Transaction
agent_ref_no	String	30	Agent reference number
ekyc_provider	String	30	ekyc provider
ekyc_ref_no	String	30	ekyc ref number
social_links	Object		Data Object
social_links_id	Long		Social Link Id
text_field	String	30	Text Field
subscriptions	Object		Data Object
subsciption_type	String	30	Subscription Type
subscription_id	String	30	Subscription Id
status	String	30	Status
first_language	String	3	Customer Preferred Language
marital_status	Integer		Marital Status
profile_category	Integer		Profile Category
dnfbp	Boolean		Designated Non-Financial Business and Professions
dpms	Boolean		Dealers in Precious Metals and Stones

Call Back API for Web Model

For Web Model, partner will provide a callback API with the below structure for updating the response based on the eKYC status.

Payload

{
    "confirmation_status": true,
    "rejection_message" :"<<failure message if confirmation status is false>>"
    "ecrn": "1058021235161541",
    "customer_status": "ACTIVE",
    "aml_scan_status": "Accepted"
}

eKYC success or failure is identified based on the confirmation_status.

If there are no other pending tasks, like additional information collection, customer will be onboarded to CDP and customer number, customer status and AML scan status will be provided.

If confirmation message status is false, then the rejection message will be updated with the actual rejection reason.

Details

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description
confirmation_status	Boolean	-	e-KYC Confirmation Status
ecrn (conditional)	String	20	CDP Customer Unique Identification Number will be present if customer is onboarded to CDP
aml_scan_status (conditional)	String	20	AML Scanned Status will be p[resent if customer is onboarded to CDP “Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done)
customer_status (conditional)	String	20	Customer Status will be present if customer is onboarded to CDP ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED
rejection_message (conditional)	String	500	rejection message will be there if the confirmation status is false

Aml CallBack API

We will be calling partner API to update the customer status and AML status.

Payload

{
   "aml_scan_status": "Accepted",
   "ecrn": "1058021235161541",
   "customer_status": "ACTIVE"
 }

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description

Name	Data Type	Max Length	Description

Name

Data Type

Max Length

Description

ecrn

String

20

CDP Customer Unique Identification Number will be present if customer is onboarded to CDP

aml_scan_status

String

20

AML Scanned Status will be p[resent if customer is onboarded to CDP

“Accepted” / “Rejected“ / “Under Investigation”/ “Failed” / “N/A” (not available when screening not done)

customer_status

String

20

Customer Status will be present if customer is onboarded to CDP

ACTIVE / KYC PENDING / INACTIVE / REJECTED / BLOCKED

EFR integration documents:

https://drive.google.com/drive/folders/1GvjUA6rQHHI5yLT5m1c2F_BbHp-lh3Hj?usp=drive_link

Master Data

ADDITIONAL_DOCUMENT

Additional Document Id	Additional Document
1	Visa
2	KYC Provider Certificate
3	ID Issued Authority Certificate

SALUTATION

Salutation Id	Salutation
Dr	Doctor
Mr	Mister
Mrs	Missis
Ms	Miss
Mx	Mix

ADDRESS TYPE

Address Type Id	Address Type
1	Resident Address
2	Permanent Address

MARITAL STATUS

Marital Status Id	Marital Status
1	Married
2	Single

Profession Category

Profession Category Id	Profession Category
PC1	Salaried
PC2	Self Employed
PC3	Business
PC4	Unemployed

Referred By

Referred By Id	Referred By
1	Walk-In
2	Relationship Manager
3	Staff
4	Customer

Relation

Relation Id	Relation
1	Self
2	Mother
3	Guardian
4	Father
8	Wife
16	Husband
32	Friend
64	Colleague
128	Employee
512	Brother
1024	Sister

Resident Type

Resident Type Id	Resident Type
100	NON-RESIDENT
101	RESIDENT
102	GCC NATIONALITY
103	SEAMEN
104	DIPLOMATS
105	TRANSIT
109	TOURIST/VISIT VISA

Social Link

Social Link Id	Social Link
1	Facebook
2	Twitter
3	Linkedin
4	Google
5	Instagram
6	WhatsApp

Transaction Volume

Transaction Volume Id	Transaction Volume
1	0-1000
2	1001-3000
3	3001 - 6000
4	6001 - 30000
5	30001 - 50000
6	50001 - 100000
7	100001 - 250000
8	250001 - 500000
9	500001 - 1000000
10	1000001- 999999999

Transaction Count

Transaction Count Id	Transaction Count
1	1 - 4
2	5 - 10
3	11 - 20
4	21 - 30
5	31 - 40
6	41 - 50
7	51 - 100

Partner EKYC Journey [EFR] - V3

Web SDK Model

EFR WEB SDK and EFR WEB SDK integration sample project:

https://drive.google.com/file/d/14vquYOenwLFjcSJ2-XmVqPxgZ3QUSTea/view?usp=sharing

Mobile SDK Model

EFR Development Kit - Android & IOS:

APIs

Access token API (API 1)

Header

Payload

Response

Request e-KYC ( API 2)

Header

Payload

Response

OCR Analyze ( API 3)

Header

Payload

Response

Face Liveness (API 4)

Payload

Response

Confirm Identity (API 5)

Header

Payload

Response

Provide Additional Information (API 6)

Header

Payload

Parameter

Response

Get Customer Profile (API 7)

Header

Parameter

Response

Call Back API for Web Model

Details

Aml CallBack API

Payload

EFR integration documents:

Master Data

Related content