This API is used to onboard a customer via eKYC by authorized entities associated with Lulu. The API provides encrypted HTML page content with a unique eKYC request Id as a response. The sequence diagram below provides further insight into the rich customer onboarding experience.
...
Customer onboarding
...
API
...
/api/v1_0/ras/onboarding
...
Authorization
...
| Table of Contents |
|---|
The partner will conduct e-KYC or KYC procedures autonomously and employ the listed APIs to enroll customers onto the Customer Data Platform (CDP). They will supply essential customer details obtained from a trusted data source (such as an e-KYC provider or government database), additional information based on country requirements, along with customer documents, including front and back images of the customer's ID, a facial image, and any e-KYC verification or confirmation reports if applicable using the customer onboard API.
Access Token API
An access token is a key to the gateway to access any other API. The API will return the access token if the user is successfully authenticated and have the 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. Token if used after its validity period restrict access to any services and a new token to be generated in this case.
API | https://{{baseUrl}}/auth/realms/cdp/protocol/openid-connect/token |
Method | POST |
Headers | Content-Type : application/ |
sender : <<sender_name>>
channel: <<channel_name>>
company: <<company_code>>
branch: <<branch_code>>
Payload
x-www-form-urlencoded | ||||||
Access Token Payload |
| |||||
Refresh Token Payload |
| |||||
Response |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | Yes | Content type |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
grant_type | String | 10 | Yes | Grant type. Will up provided |
scope | String | 60 | Yes | Scope name. Will be provided |
client_id | String | 60 | Yes | Client Id. Will be provided |
client_secret | String | 60 | Yes | Client secret. Will be provided |
username | String | 60 | Yes | Admin user name |
password | String | 60 | Yes | Admin password |
Response
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
token_type | String | - | Yes | Token type |
scope | String | - | Yes | Scope details |
access_token | String | 600 | Yes | Access token to access the APIs |
refresh_token | String | 600 | Yes | refresh token to refresh the Token. |
expires_in | Integer | - | Yes | Token expiry time in seconds |
refresh_expires_in | Integer | - | Yes | Refresh Token expiry time in seconds |
Customer Lookup API v2
API to be used to look up customer information by ID type, ID number and channel.
API | ||||||
Authorization | Bearer Token | |||||
Method | POST | |||||
Headers | Content-Type:application/json | |||||
Payload |
| |||||
Success Response |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||||||
Subscription Pending Response |
| |||||
Customer ID not found |
|
|
|
|
|
| ||||||
Other Failure Response |
|
|
|
|
|
|
Response
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | Yes | Content type |
Ocp-Apim-Subscription-Key | String | 32 | Yes | Subscription key |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
idType | String | 3 | Yes | Customer id type code |
idNumber | String | 30 | Yes | Customer id/Number |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
message | String | 255 | Message |
data | Object | - | Data object |
ecrn | String | 16 | Customer unique identification number |
first_name | String | 255 | Customer first name |
middle_name | String | 255 | Customer middle name |
last_name | String | 255 | Customer last name |
agent_location_id | String | 20 | Onboarded Agent |
primary_mobile_number | String | 20 | Customer mobile no |
email_id | String | 30 | Customer email |
customer_status | String | 20 | Possible values : "ACTIVE", "KYC_PENDING", "INACTIVE", "BLOCKED", "DISABLED" |
aml_scan_status | String | 20 | Possible values : "Accepted" , "Under Investigation" , "Rejected", "Failed" |
id_status | String | 20 | Possible values : "Active", "Expired" |
id_date_of_expiry | String |
| YYYY-MM-DD format |
Individual Onboarding API
API to be used to onboard customer.
API | https://{{baseUrl}}/caas-lcm/api/v1/CAAS/onBoarding/customer | |||||
Authorization | Bearer Token | |||||
Method | POST | |||||
Headers | Content-Type:application/json | |||||
Payload |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Header
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
Content-Type
...
String
...
36
...
Yes
...
Content type
...
sender
...
String
...
60
...
Yes
...
Agent / Partner name.
...
channel
...
String
...
30
...
Yes
...
Ripple / Direct
...
company
...
String
...
6
...
Yes
...
Will be shared
...
branch
...
String
...
6
...
Yes
...
Will be shared
...
Ocp-Apim-Subscription-Key
...
String
...
32
...
Yes
...
Subscription key
Payload
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
salutation
...
String
...
3
...
Yes
...
Customer salutation
...
first_name
...
String
...
255
...
Yes
...
Customer first name
...
middle_name
...
String
...
255
...
No
...
Customer middle name
...
last_name
...
String
...
255
...
Yes
...
Customer last name
...
nationality
...
String
...
2
...
Yes
...
Customer nationality
...
date_of_birth
...
String
...
-
...
Yes
...
Customer date of birth
...
country_of_birth
...
String
...
2
...
Yes
...
Customer country of birth
...
visa_type_code
...
String
...
3
...
Yes
...
Sender visa type code
...
gender
...
String
...
1
...
Yes
...
Customer gender. Possible values are M and F
...
mobile_number
...
String
...
20
...
Yes
...
Customer mobile no
...
...
String
...
30
...
Yes
...
Customer email
...
profession_code
...
String
...
4
...
Yes
...
Profession code
...
country_code
...
String
...
2
...
Yes
...
Customer Country code
...
country_of_residence
...
String
...
2
...
Yes
...
Country of residence
...
sender_id
...
object
...
-
...
Yes
...
Sender details
...
id_code
...
String
...
3
...
Yes
...
Customer id type code. Example : 4 for emirates ID
...
id
...
String
...
30
...
Yes
...
Customer ID / number. Example : Emirates ID
...
issued_country_code
...
String
...
2
...
Optional
...
Customer id issued country
...
issued_by
...
String
...
255
...
Optional
...
Customer id issued by
...
issued_on
...
String
...
-
...
Optional
...
YYYY-MM-DD format
...
valid_through
...
String
...
-
...
Optional
...
YYYY-MM-DD format
...
id_front
...
Object
...
-
...
Optional
...
...
base64_data
...
String
...
-
...
Yes
...
PDF content base 64 data
...
content_type
...
String
...
30
...
Yes
...
Content type. application/pdf
...
document_type
...
String
...
255
...
Yes
...
Document type description
...
id_back
...
Object
...
-
...
Optional
...
...
base64_data
...
String
...
-
...
Yes
...
PDF content base 64 data
...
content_type
...
String
...
30
...
Yes
...
Content type. application/pdf
...
document_type
...
String
...
255
...
Yes
...
...
sender_address
...
Object
...
-
...
Yes
...
Data object
...
address_type
...
String
...
20
...
Yes
...
Sender address type like Present, Permanent
...
address_line
...
String
...
70
...
Yes
...
Building name
...
street_name
...
String
...
70
...
Yes
...
Street name
...
country_code
...
String
...
2
...
Yes
...
Country
...
country_subdivision
...
String
...
35
...
Yes
...
Sender country sub division
...
town_name
...
String
...
35
...
Yes
...
Sender town name
...
post_code
...
String
...
12
...
Yes
...
Sender postal area code. Example: Zipcode, Pincode
...
customer_classification
...
Object
...
-
...
Yes
...
Data object
...
annual_income_range_id
...
String
...
3
...
Yes
...
Customer annual income range id
...
employer_name
...
String
...
255
...
Yes
...
Employer name(eg:LULU)
...
income_type
...
Integer
...
-
...
Yes
...
Customer Income Type
...
txvol_month
...
Integer
...
-
...
Yes
...
Transaction volume per month
...
txn_count_month
...
Integer
...
-
...
Yes
...
Transaction count per month
Response
...
Name
...
Data Type
...
Max Length
...
Name
...
Description
...
Name
...
Data Type
...
Max Length
...
Name
...
Description
...
status
...
String
...
255
...
Yes
...
status description
...
status_code
...
Int
...
-
...
Yes
...
Status code
...
data
...
Object
...
-
...
Yes
...
Data object
...
customer_number
...
String
...
16
...
Yes
...
Customer unique identification number
...
customer_status
...
String
...
20
...
Yes
...
Customer status. Possible status : "ACTIVE", "KYC_PENDING" "INACTIVE" "BLOCKED"
...
aml_scan_status
...
String
...
20
...
Yes
...
AML status. Possible Status : "Accepted" , "Under Investigation" , "Rejected"
EKYC Presentation Request
...
API
...
/api/v1/request
...
Authorization
...
Bearer Token
...
Method
...
POST
...
Headers
...
Content-Type:application/json
...
Payload
...
| Code Block |
|---|
{
"channel": "BRANCH",
"agentLocationId": "784101",
"ekycProvider": "EFR",
"ecrn": "123456789",
"primaryMobileNumber": "+971502106707",
"emailId": "irfanmtp1@gmail.com"
} |
...
Success Response
...
| Code Block |
|---|
{
"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>>"
}
}
} |
...
Authentication Failure
...
| Code Block |
|---|
{
"timestamp": "2022-12-05T13:44:31.557+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/api/v1/request"
} |
...
Other Failure Response
...
| Code Block |
|---|
{
"status": "failure",
"statusCode": 400,
"errorCode": 40000,
"message": "Payload not readable or corrupt"
} |
Header
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
Content-Type
...
String
...
36
...
Yes
...
Content type
Payload
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
channel
...
String
...
20
...
Yes
...
Channel
...
agentLocationId
...
String
...
6
...
Yes
...
Unique Identifier to identify the requester
...
ekycProvider
...
String
...
30
...
Yes
...
EKYC Provider
...
ecrn
...
String
...
255
...
Yes
...
Customer Number
...
primaryMobileNumber
...
String
...
20
...
No
...
Primary Mobile Number
...
emailId
...
String
...
120
...
No
...
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
...
EKYC Request unique identification number
...
ekyc_request_data
...
Object
...
-
...
Data object
...
ekyc_portal_html
...
String
...
4000
...
Base 64 Encrypted EKYC Portal Html content
Lookup
API to be used to look up customer information by id type, id number and mobile number.
...
API
...
/api/v1_0/ras/lookup
...
Authorization
...
Bearer Token
...
Method
...
POST
...
Headers
...
Content-Type:application/json
sender : <<sender_name>>
channel: <<channel_name>>
company: <<company_code>>
branch: <<branch_code>>
...
Payload
...
| Code Block |
|---|
{
"mobile_number": "+96864313460",
"id_code": "15",
"id": "225522319"
}
|
...
Response
...
| Code Block |
|---|
{
"status": "success",
"status_code": 200,
"data": {
"customer_number": "5121121220000006",
"first_name": "CHOCKY",
"middle_name": "NAIR",
"last_name": "DO",
"mobile_number": "+96864313460",
"email": "CHOCKY.96864313460@gmail.com",
"customer_status": "ACTIVE",
"aml_scan_status": "Accepted",
"id_status" : "Active",
"id_details": [
{
"id_code": "15",
"id": "225522319",
"valid_through": "2030-12-10"
}
]
}
}
|
...
Response (No customer found)
...
| Code Block |
|---|
{
"status": "failure",
"status_code": 404,
"error_code": 40100,
"message": "Customer not found"
}
|
...
Response (Mobile number NOT matched)
...
| Code Block |
|---|
{
"status": "failure",
"status_code": 404,
"error_code": 40100,
"message": "ID matched, but mobile number not matched"
}
|
Header
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
Content-Type
...
String
...
36
...
Yes
...
Content type
...
sender
...
String
...
60
...
Yes
...
Agent / Partner name.
...
channel
...
String
...
30
...
Yes
...
Ripple / Direct
...
company
...
String
...
6
...
Yes
...
Will be shared
...
branch
...
String
...
6
...
Yes
...
Will be shared
...
Ocp-Apim-Subscription-Key
...
String
...
32
...
Yes
...
Subscription key
Payload
...
Name
...
Data Type
...
Max Length
...
Mandatory
...
Description
...
mobile_number
...
String
...
20
...
Yes
...
Customer mobile no
...
id_code
...
String
...
3
...
Yes
...
Customer id type code
...
id
...
String
...
30
...
Yes
...
Customer id/Number
Response
Name
Data Type
Max Length
Name
Description
Name
Data Type
Max Length
Name
Description
status
String
255
Yes
status description
status_code
Int
-
Yes
Status code
data
Object
-
Yes
Data object
customer_number
String
16
Yes
Customer unique identification number
first_name
String
255
Yes
Customer first name
middle_name
String
255
Yes
Customer middle name
last_name
String
255
Yes
Customer last name
mobile_number
String
20
Yes
Customer mobile no
String
30
Yes
Customer email
customer_status
String
20
Yes
Possible values : "ACTIVE", "KYC_PENDING", "INACTIVE", "BLOCKED", "DISABLED", "SUBSCRIPTION_PENDING"
aml_scan_status
String
20
Yes
Possible values : "Accepted" , "Under Investigation" , "Rejected", "Failed"
id_status
String
20
Yes
Possible values : "Active", "Expired"
id_details
Object
Yes
id details
id_code
String
3
Yes
Customer id type code
id
String
30
Yes
customer id/Number
valid_through
String
Yes
| ||||||
Success Response |
| |||||
Validation Failure Response - Customer Not Acceptable / Under Compliance Investigation |
| |||||
Validation Failure Response - Mandatory Fields Missing/ Invalid Data |
| |||||
Authentication Failure Response |
|
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String |
| Yes | Content Type |
Authorization | String |
| Yes | Authorization Token |
Payload
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
agent_location_id | String | 30 | Yes | Agent Location Id |
channel | String | 30 | Yes | Channel |
salutation* | String | 3 |
| Salutation(Mr, Ms) , Salutation Id As per SALUTATION master |
first_name | String | 30 | Yes | First Name |
middle_name | String | 30 |
| Middle Name |
last_name | String | 30 | yes | Last Name |
preferred_name | String | 30 |
| Preferred Name |
nationality* | String | 2 | yes | Nationality code as per NATIONALITY Master |
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 |
| yes | Date of Birth in “YYYY-MM-DD” Format |
country_of_birth* | String | 2 | yes | Country of Birth code as per COUNTRY Master |
place_of_birth | String | 100 |
| Place of Birth |
resident_type_id* | Long |
|
| Resident Type Id as per RESIDENT_TYPE Master |
country_of_residence* | String | 2 | yes | Resident Country code as per COUNTRY master |
gender | Male | 12 | yes | Gender |
mothers_maiden_name | String | 30 |
| Mothers Name |
primary_mobile_number | String | 30 | yes | Primary Mobile Number |
secondary_mobile_number | String | 30 |
| Secondary Mobile Number |
email_id | String | 30 | yes | 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 |
document_id* | String |
| Document Id as per DOCUMENT_TYPE master | |
base64_data | String |
|
| Base64 Data |
content_type | String |
|
| Content Type |
id_details | Object |
|
| Data Object |
id_type | Long |
| Yes | Id Type |
id_number | String | 30 | Yes | Id Number |
name_as_per_id | String | 30 |
| Name as per Id |
issued_country | String | 2 |
| Issued Country code as per COUNTRY master |
issued_by | String | 30 |
| Issued By |
issued_at | String | 30 |
| Issued At |
issued_on | Date |
|
| Issued On in “YYYY-MM-DD” Format |
date_of_expiry | Date |
|
| Date of Expiry in “YYYY-MM-DD” Format |
visa_number | String | 30 |
| Visa Number |
visa_expiry_date | Date |
|
| Visa Expiry Date in “YYYY-MM-DD” Format |
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 |
| yes | 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 |
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 |
Response
Name | Data Type | Max Length | Description |
|---|---|---|---|
status | String | 255 | status description |
status_code | Int | - | Status code |
data | Object | - | Data object |
ecrn | String | 20 | Customer Number |
aml_scan_status | String | 20 | AML Scanned Status “Accepted”/”Under investigation”/”Failed”/”NA” |
customer_status | String | 20 | Customer Status |