These APIs are used to onboard a customer via e-KYC by authorized entities associated 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

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 HTML Model
Web SDK Model
Mobile SDK Model

Web HTML model

The API provides encrypted HTML page content with a unique e-KYC request Id as a response. The sequence diagram below provides further insight into the rich customer onboarding experience.

...

Image Added

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.

Image Added

EFR WEB SDK and EFR WEB SDK integration sample project:

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.

Image Removed

SDKs. EFR SDK will take care of OCR and Face liveness.

Image Added

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.

...

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.

...

API

https://{{baseUrl}}/ekyc/api/v1/request

Authorization

Bearer Token

Method

POST

Headers

Content-Type:application/json

Payload

Code Block

language	json

{
  "channel": "WEB",
  
  
  
  
  "ekyc_provider": "EFR",
  "ekyc_model": "WEB",
  "ecrn": "<<ecrn>>",
  "primary_mobile_number": "<<customer_mobile>>",
  "email_id": "<<customer_email_id>>"
}

Success Response for

Status

title	WEB

model

Http status Code :200

Code Block

language	json

{
    "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

Status

colour	Purple
title	SDK

model

Http status Code :200

Code Block

language	json

{
    "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

Code Block

language	json

{
    "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

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 46001,
    "message": "eKYC not Configured for the Agent!"
}

Failure Response

Invalid e-KYC Provider

Http status Code :200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 46002,
    "message": "Invalid eKYC Provider"
}

Failure Response

Invalid e-KYC Model for e-KYC Provide

Http status Code :200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 46003,
    "message": "Invalid eKYC Model for eKYC Provider!"
}

Authentication Failure

Http status Code :401

Code Block

language	json

{
  "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

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47001,
  "message": "EFR eKYC Service is Down!"
}

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47002,
  "message": "EFR Web Portal is Down!"
}

...

Name

Data Type

Max Length

Mandatory

Description

channel

String

20

Status

colour	Green
title	mandatory

Channel

agent_location_id /

agentLocationId

String

6

Status

colour	Green
title	mandatory

Unique Identifier to identify the requester

ekyc_provider /

ekycProvider

String

30

Status

colour	Green
title	mandatory

EKYC Provider

ekyc_model /

ekycModel

String

30

Status

colour	Green
title	mandatory

EKYC Model:

Status

title	WEB

/

Status

title	FACE_WEB

/

Status

colour	Blue
title	SDK

ecrn

String

255

Status

colour	Yellow
title	CONDITIONAL

CDP customer unique identification Number, provide only for existing CDP customer.

primary_mobile_number PrimaryMobileNumber

String

20

Status

colour	Yellow
title	CONDITIONAL

Primary Mobile Number

email_id / emailId

String

120

Status

colour	Yellow
title	CONDITIONAL

Email ID

...

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

Status

title	WEB

e-KYC model.

ekyc_sdk_configuration

String

4000

e-KYC SDK Configuration Data only for the

Status

title	SDK

e-KYC model.

ekyc_sdk_secretKey

Object

e-KYC SDK Secret Key data is only for the

Status

title	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

Code Block

language	json

{
  "ekycRequestId": "<<ekycRequestId>>",
  "document": "<<id_document_front_base64>>",
  "documentBack": "<<id_document_back_base64>>"
}

Success Response

Http status Code :200

Code Block

language	json

{
  "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

Code Block

language	json

{
  "timestamp": "2022-12-05T13:44:31.557+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/api/v1/request"
}

Bad Request

Http status Code :200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 400,
    "errorCode": 400,
    "message": "ekycRequestId is mandatory"
}

e-KYC Request Id not found (Not found)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 404,
  "errorCode": 46004,
  "message": "eKYC RequestId not found!"
}

e-KYC Provider Mismatch (Bad Request)

Http status Code :200

Code Block

language	json

{
  "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

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46006,
  "message": "eKYC Request Expired!"
}

e-KYC Request already Failed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46007,
  "message": "eKYC Failed, Initiate new Request!"
}

e-KYC Request already Rejected (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46008,
  "message": "eKYC Rejected, Initiate new Request!"
}

e-KYC Request already Completed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46009,
  "message": "eKYC already Completed!"
}

Partner (e-KYC Provider)Service Failure

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47001,
  "message": "EFR eKYC Service is Down!"
}

...

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

Code Block

language	json

{
  "ekycRequestId": "<<ekycRequestId>>",
  "data": "<<face_data_from_sdk>>"
}

Success Response

Http status Code :200

Code Block

language	json

{
    "status": "success",
    "statusCode": 200,
    "data": {
        "data": "<<encrypted_face_data_response>>"
    }
}

Authentication Failure

Http status Code :401

Code Block

language	json

{
  "timestamp": "2022-12-05T13:44:31.557+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/api/v1/request"
}

Bad Request

Http status Code :200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 400,
    "errorCode": 400,
    "message": "ekycRequestId is mandatory"
}

e-KYC Request Id not found (Not found)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 404,
  "errorCode": 46004,
  "message": "eKYC RequestId not found!"
}

e-KYC Provider Mismatch (Bad Request)

Http status Code :200

Code Block

language	json

{
  "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

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46006,
  "message": "eKYC Request Expired!"
}

e-KYC Request already Failed (Internal Server Error)

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46007,
  "message": "eKYC Failed, Initiate new Request!"
}

e-KYC Request already Rejected (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46008,
  "message": "eKYC Rejected, Initiate new Request!"
}

e-KYC Request already Completed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46009,
  "message": "eKYC already Completed!"
}

Partner (e-KYC Provider)Service Failure

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47001,
  "message": "EFR eKYC Service is Down!"
}

...

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.

...

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

Code Block

language	json

{
    "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

Code Block

language	json

{
    "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

Code Block

language	json

{
    "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

Code Block

language	json

{
    "status": "success",
    "statusCode": 200,
    "data": {
        "confirmation_status": false,
        "rejection_message" :"<<failure message>>"
    }
}

Authentication Failure

Http status Code :401

Code Block

language	json

{
  "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

Code Block

language	json

{
  "status": "failure",
  "statusCode": 404,
  "errorCode": 46004,
  "message": "eKYC RequestId not found!"
}

e-KYC Provider Mismatch (Bad Request)

Http status Code :200

Code Block

language	json

{
  "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

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46006,
  "message": "eKYC Request Expired!"
}

e-KYC Request already Failed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46007,
  "message": "eKYC Failed, Initiate new Request!"
}

e-KYC Request already Rejected (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46008,
  "message": "eKYC Rejected, Initiate new Request!"
}

e-KYC Request already Completed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46009,
  "message": "eKYC already Completed!"
}

Partner (e-KYC Provider)Service Failure

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47001,
  "message": "EFR eKYC Service is Down!"
}

Validation Failure Response - Customer Under Compliance Investigation

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 500,
    "errorCode": 45013,
    "message": "Customer under Compliance investigation!"
}

Validation Failure Response - Blocked Customer

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 45051,
    "message": "Customer can not be Accepted"
}

Validation Failure Response - Blocked Customer Onboarding Failed

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404500,
    "errorCode": 4505147006,
    "message": "Customer can not be Acceptedonboarding failed!"
}

Customer Onboarding Failednot Residing in the country

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 500,
    "errorCode": 4700645004,
    "message": "Customer onboarding failedis currently not in the country!""
}

CDP Service is Down

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47006,
  "message": "CDP Service is Down!"
}

...

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

Status

colour	Green
title	ACTIVE

/

Status

colour	Yellow
title	KYC PENDING

/

Status

colour	Yellow
title	INACTIVE

/

Status

colour	Red
title	REJECTED

/

Status

colour	Red
title	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

Code Block

language	json

{
    "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

Code Block

language	json

{
    "status": "success",
    "statusCode": 200,
    "data": {
        "ecrn": "1058021235161541",
        "customer_status": "ACTIVE",
        "aml_scan_status": "Accepted"
    }
}

Authentication Failure

Http status Code :401

Code Block

language	json

{
  "timestamp": "2022-12-05T13:44:31.557+00:00",
  "status": 401,
  "error": "Unauthorized",
  "path": "/api/v1/request"
}

Bad Request

Http status Code :200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 400,
    "errorCode": 46022,
    "message": " emailId is mandatory in request !"
}

e-KYC Request Id not found (Not found)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 404,
  "errorCode": 46004,
  "message": "eKYC RequestId not found!"
}

e-KYC Request Expired (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46006,
  "message": "eKYC Request Expired!"
}

e-KYC Request already Failed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46007,
  "message": "eKYC Failed, Initiate new Request!"
}

e-KYC Request already Rejected (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46008,
  "message": "eKYC Rejected, Initiate new Request!"
}

e-KYC Request already Completed (Internal Server Error)

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 46009,
  "message": "eKYC already Completed!"
}

Validation Failure Response - Customer Under Compliance Investigation

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 500,
    "errorCode": 45013,
    "message": "Customer under Compliance investigation!"
}

Validation Failure Response - Blocked Customer

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 45051,
    "message": "Customer can not be Accepted"
}

Customer onboarding failed

HttpStatusCode : 200

Code Block

language	json

{
    "status": "failure",
    "statusCode": 500,
    "errorCode": 47006,
    "message": "Customer onboarding failed!"
}

CDP Service is Down

Http status Code :200

Code Block

language	json

{
  "status": "failure",
  "statusCode": 500,
  "errorCode": 47006,
  "message": "CDP Service is Down!"
}

...

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

Status

colour	Green
title	ACTIVE

/

Status

colour	Yellow
title	KYC PENDING

/

Status

colour	Yellow
title	INACTIVE

/

Status

colour	Red
title	REJECTED

/

Status

colour	Red
title	BLOCKED

Get Customer Profile (API 7)

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

Response

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

API

https://{{baseUrl}}/caas/api/v2/customer/{{ecrn}}

Authorization

Bearer Token

Method

GET

Headers

Content-Type:application/json

Payload

Code Block
None

Success Response

Http status Code :200

Code Block

language	json

{
    "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

Code Block

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 45001,
    "message": "Customer not found"
}

Customer Not Subscribed Failure Response

Http status Code :200

{

Code Block

language	json

language	json

{
    "status": "failure",
    "statusCode": 404,
    "errorCode": 45003,
    "message": "Customer not Subscribed"
}

Authentication Failure Response

Http status Code :401

Code Block

language	json

{
    "timestamp": "2023-03-15T14:26:24.292+00:00",
    "status": 401,
"failure    "error": "Unauthorized",
    "statusCode": 404,
    "errorCode": 45003,
    "message": "Customer not Subscribed"
}

Authentication Failure Response

Http status Code :401

Code Block

language	json

{
    "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

...

Content-Type

...

String

...

36

...

Status

colour	Green
title	MANDATORY

...

Content type

...

Authorization

...

String

...

Status

colour	Green
title	MANDATORY

...

Authorization Token

Parameter

...

Name

...

Data Type

...

Max Length

...

Mandatory

...

Description

...

ecrn

...

String

...

20

...

Status

colour	Green
title	MANDATORY

...

Customer unique identification number

    "message": "",
    "path": "/api/v1/customer/7841001228796988"
}

Header

Name

Data Type

Max Length

Mandatory

Description

Content-Type

String

36

Status

colour	Green
title	MANDATORY

Content type

Authorization

String

Status

colour	Green
title	MANDATORY

Authorization Token

Parameter

Name

Data Type

Max Length

Mandatory

Description

ecrn

String

20

Status

colour	Green
title	MANDATORY

Customer unique identification number

Response

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
id_detailsaddressList	Object		Data Object
idaddress_type_id	Long		Address Type Id Type
idbuilding_numbername	String	30Id	NumberBuilding Name
name_as_per_idstreet_name	String	30	Name as per Id	issued_Street Name
landmark	String	30	Landmark
country	String	2	Issued Country	issued_byCountry
state	String	30	State
district	String	30	District
city	String	30	City
zip	Long		Zip
mobile_number	String	30	Issued By	issued_atMobile Number
status	String	30	Issued AtDisable
issuedcustomer_onclassification	DateObject	Issued	OnData Object
datecustomer_oftype_expiryid	DateLong		Date of Expiry
visa_number	String	30	Visa Number
visa_expiry_date	Date		Visa Expiry Date
default_statusCustomer 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	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_typeSocial 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		Address Type Id
building_name	String	30	Building Name
street_name	String	30	Street Name
landmark	String	30	Landmark
country	String	2	Country
stateCompliance 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	State	districtGroup Employee Code
personal_mohre_id	String	30	District	cityPersonal Mohre Id
customer_cards	String	30	City
zip	Long		Zip
mobileCustomer Cards
card_number	String	30	Mobile Card Number
statusincome_type	String	30Disable	Income Type
customerprofession_classificationcategory	ObjectString	30	Data ObjectProfession Category
customerreason_typefor_idacc	LongString		Customer Type Id
annual_income_range_id	Long		Annual Income Range
annual_income_currency_code30	Reason for ACC
referred_by_type	Integer		Referred By Type
referred_by	String	30	Annual Income Currency Code	social_security_numberReffered By
txn_vol_month	String	30	Social Security Number
tax_registration_number	Long		Tax Registration Number
txn_issued_country	String	2	Tax Issued Country
employer_nameTransaction Volume Month
txn_count_month	String	30	Transaction Count Month
show_remarks_on_txn	Boolean		show Remarks on transaction
customer_remarks	String	30	Employer Name
employer_address	String	30	Employer Address
employer_phoneRemarks on Transaction
agent_ref_no	String	30	Employer Phone	employer_ecrnAgent reference number
ekyc_provider	String	30Employer	ECRNekyc provider
employerekyc_establishmentref_idno	String	30	Employer Establishment ID	risk_rating_id	Longekyc ref number
social_links	Object		Risk Rating ID	compliance_categoryData Object
social_links_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_codeSocial 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	Group Employee CodeStatus
personalfirst_mohre_idlanguage	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

Code Block

language	json

{
    "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

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

Code Block

language	json

{
    "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

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

Status

colour	Green
title	ACTIVE

/

Status

colour	Yellow
title	KYC PENDING

/

Status

colour	Yellow
title	INACTIVE

/

Status

colour	Red
title	REJECTED

/

Status

colour	Red
title	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

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

Name	Data Type	Max Length	Description

confirmation_status

Boolean

-

e-KYC Confirmation Status

ecrn (conditional)

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

(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

Status

colour	Green
title	ACTIVE

/

Status

colour	Yellow
title	KYC PENDING

/

Status

colour	Yellow
title	INACTIVE

/

Status

colour	Red
title	REJECTED

/

Status

colour	Red
title	BLOCKED

rejection_message

(conditional)

String

500

rejection message will be there if the confirmation status is false

EFR integration documents:

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

Master Data

Anchor

	ADDITIONAL_DOCUMENT
	ADDITIONAL_DOCUMENT

View file

name	CDP-Master Values.xlsx

ADDITIONAL_DOCUMENT

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

...

Versions Compared

Old Version 11

New Version Current

Key

Web HTML model

Web SDK Model

EFR WEB SDK and EFR WEB SDK integration sample project:

Mobile SDK Model

EFR Development Kit - Android & IOS:

APIs

Access token API (API 1)

Request e-KYC ( API 2)

OCR Analyze ( API 3)

Face Liveness (API 4)

Confirm Identity (API 5)

Provide Additional Information (API 6)

Get Customer Profile (API 7)

Response

Header

Parameter

Header

Parameter

Response

Call Back API for Web Model

Details

Call Back API for Web Model

Details

Aml CallBack API

Payload

EFR integration documents:

Master Data

Page Comparison

Versions Compared

Old Version 11

New Version Current

Key

Web HTML model

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)

Request e-KYC ( API 2)

OCR Analyze ( API 3)

Face Liveness (API 4)

Confirm Identity (API 5)

Provide Additional Information (API 6)

Get Customer Profile (API 7)

Response

Header

Parameter

Header

Parameter

Response

Call Back API for Web Model

Details

Call Back API for Web Model

Details

Aml CallBack API

Payload

EFR integration documents:

Master Data