The Partner Retail Account Application API is available to partner institutions to initiate the basic account opening process for their new retail customers and to update KYC details of the customer once document verification is completed from their end. The scanned documents need to be uploaded separately to a SFTP server. Post verification of the documents by the RAKBank operations and compliance teams, the customer onboarding and account opening would be completed and the status would be notified to the partner.
The on-boarding process invloves three stages during which the Partner Retail Account Application API is invoked by the Partner:
- Stage 1 : The applicant enters his/her basic details and uploads scanned copy of the Emirates ID on the Partner App
- Stage 2 : The partner performs physical verification of the applicant's Emirates ID and collects KYC details, signed Consent and FATCA/CRS form copies of the applicant
- Stage 3 : The applicant provides additional KYC documents/details if requested at the end of Stage 2 by RAKBank Compliance Team
Version 1.1.0
- Added new operation UpdateRetailAccountApplication that allows you to pass certain details of the customer along with status update, once customer verification has been completed on your end.
- UpdateRetailAccountApplicationStatus can be used only when status needs to be updated for eg. in case of rejections.
- "demographic" property has been renamed to "countries_dealing_with". Similarly a few fatca related fields have been renamed.
Version 1.1.1
- Added field employer_name under employment. Corrected length of field IBAN to 23.
- Added "income" under applicant.
- Corrected Valid values for employment_type.
- New documents.type "VISAUID" added, mandatory for UpdateRetailAccountApplication operation.
Version 1.2.0
- status field in application_status definition can also have the value "ADDITIONAL_COMPLIANCE_INFO_PROVIDED" - indicating that additional information/documents requested by RAKBank Compliance team has been provided by partner.
- Added fields "remarks" under application_status. Remarks can be provided when passing status as 'ADDITIONAL_COMPLIANCE_INFO_PROVIDED' in UpdateRetailAccountApplicationStatus operation.
- Added field "is_addtnl_doc_provided" under application_status. Indicates whether additional customer document requested by RAKBank Compliance team has been uploaded by the partner to the SFTP server. Valid values: true or false. Mandatory when passing status as 'ADDITIONAL_COMPLIANCE_INFO_PROVIDED' in UpdateRetailAccountApplicationStatus operation.
Version 1.3.0
- Added "second_nationality" which is mandatory for customers with dual nationality.
- Added "monthly_income" under income.
- Additional "employment_type" values added for dependants.
- "employer_name" should have sponsor name when "employment_type" is passed as Retired/Housewife/PENSIONER.
- Document type VISA, VISAUID are not required to be passed in case of GCC Nationals.
- "industry_subsegment_code" now takes a pipe separated list of values and required only when applicant's "employment_type" is 'Self employed' or 'A' (Salaried & Self-employed).
| Attachment | Size |
|---|---|
 Postman Collection | 7.72 KB |
Basepath
/v1
API Developer
production
development
https://sandboxapi.rakbank.ae/sb/api
Paths
/retail/account_applications
post /retail/account_applications
This is used to submit an application for a new account opening for a new retail customer.
clientIdHeader
X-IBM-Client-Id
(apiKey located in header)
oauth
oauth
(oauth2 application)
Token URL
https://sandboxapi.rakbank.ae/rb/api/v1/partner_auth/token
Scopes
retail_account_applications
retail_account_applications
Required in body
object
All the customer and account details for creating a retail account application
Content-Type
Optional in header
string
application/json
Accept
Optional in header
string
application/json
201
401
Unauthorized
403
Forbidden
422
Error
500
Internal Server Error
Example Request
Example Response
POST https://sandboxapi.rakbank.ae/sb/api/v1/retail/account_applications
/retail/account_applications/{account_application_id}
post /retail/account_applications/{account_application_id}
This is used to update KYC details of an applicant after completion of document verification on your end.
clientIdHeader
X-IBM-Client-Id
(apiKey located in header)
oauth
oauth
(oauth2 application)
Token URL
https://sandboxapi.rakbank.ae/rb/api/v1/partner_auth/token
Scopes
retail_account_applications
account_application_id
Required in path
string
Application Id returned in the CreateRetailAccountApplication operation response.
{
"maxLength": 30
}retail_account_applications
Required in body
object
additional details of the application
Content-Type
Optional in header
string
application/json
Accept
Optional in header
string
application/json
200
401
Unauthorized
403
Forbidden
422
Error
500
Internal Server Error
Example Request
Example Response
POST https://sandboxapi.rakbank.ae/sb/api/v1/retail/account_applications/{account_application_id}
/retail/account_applications/{account_application_id}/application_status
post /retail/account_applications/{account_application_id}/application_status
This operation is used to update the statuses "CUSTOMER_REJECTED" or "ADDITIONAL_COMPLIANCE_INFO_PROVIDED" during Stages 2 and 3 of the on-boarding process respectively.
clientIdHeader
X-IBM-Client-Id
(apiKey located in header)
oauth
oauth
(oauth2 application)
Token URL
https://sandboxapi.rakbank.ae/rb/api/v1/partner_auth/token
Scopes
retail_account_applications
MsgId
Required in header
string
Unique Id sent by client. Value should be a unique identifier of the request in UUID format.
{
"maxLength": 50
}account_application_id
Required in path
string
Application Id returned in the CreateRetailAccountApplication operation response.
{
"maxLength": 30
}application_status
Required in body
object
status of the application
Content-Type
Optional in header
string
application/json
Accept
Optional in header
string
application/json
200
200 OK
401
Unauthorized
403
Forbidden
422
Error
500
Internal Server Error
Example Request
Example Response
POST https://sandboxapi.rakbank.ae/sb/api/v1/retail/account_applications/{account_application_id}/application_status
Definitions
Response in case of error
{
"properties": {
"response_code": {
"type": "string",
"description": "API specific error code"
},
"response_message": {
"type": "string",
"description": "breif details of the error"
},
"status": {
"type": "string",
"description": "HTTP Status"
},
"description": {
"type": "string",
"description": "detailed description of the error"
},
"property": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"response_code",
"response_message",
"status"
]
}
{
"properties": {
"status": {
"type": "string",
"enum": [
"CUSTOMER_VERIFIED",
"CUSTOMER_REJECTED",
"ADDITIONAL_COMPLIANCE_INFO_PROVIDED"
],
"description": "Status to be updated. Valid values: \n- CUSTOMER_VERIFIED - indicating customer has been physically verified by partner. This status is can be passed in UpdateRetailAccountApplication operation during Stage 2 of the on-boarding process and all applicant fields marked as \"Required in the UpdateRetailAccountApplication operation\" must be supplied. \n- CUSTOMER_REJECTED - indicating customer has been rejected by partner. This status can be passed in UpdateRetailAccountApplicationStatus operation during Stage 2.\n- ADDITIONAL_COMPLIANCE_INFO_PROVIDED - indicating that additional information/documents requested by RAKBank Compliance team has been provided by partner. This status can be passed in UpdateRetailAccountApplicationStatus operation during Stage 3 of the on-boarding process.'\n",
"example": "CUSTOMER_VERIFIED"
},
"remarks": {
"type": "string",
"maxLength": 3000,
"description": "Remarks from partner if any. Remarks can be provided when passing status as 'ADDITIONAL_COMPLIANCE_INFO_PROVIDED' in UpdateRetailAccountApplicationStatus operation."
},
"is_addtnl_doc_provided": {
"type": "boolean",
"description": "Indicates whether additional customer document requested by RAKBank Compliance team has been uploaded by the partner to the SFTP server. Valid values: true or false. Mandatory when passing status as 'ADDITIONAL_COMPLIANCE_INFO_PROVIDED' in UpdateRetailAccountApplicationStatus operation.",
"example": true
}
},
"additionalProperties": false,
"required": [
"status"
]
}
{
"properties": {
"account_application_id": {
"type": "string",
"maxLength": 30,
"description": "Read only field. Application Id.",
"example": "YAP-0000000001"
},
"applicant": {
"description": "Holds applicant details",
"$ref": "#/definitions/applicant"
},
"account": {
"description": "Holds account details. Required in the CreateRetailAccountApplication operation.",
"$ref": "#/definitions/account"
},
"application_status": {
"description": "Holds account status. Required in the UpdateRetailAccountApplication operation.",
"$ref": "#/definitions/application_status"
}
},
"additionalProperties": false,
"required": [
"applicant"
]
}
Response object.
{
"properties": {
"account_application_id": {
"type": "string",
"maxLength": 30,
"description": "Application Id for this request.",
"example": "YAP-0000000001"
}
},
"additionalProperties": false,
"required": [
"account_application_id"
]
}
Holds the details of the Applicant
{
"properties": {
"first_name": {
"type": "string",
"maxLength": 80,
"description": "Applicant First Name. Required in the CreateRetailAccountApplication operation.",
"example": "John"
},
"middle_name": {
"type": "string",
"maxLength": 80,
"description": "Applicant Middle Name. Optional field. Can be passed in the CreateRetailAccountApplication operation.",
"example": "Smith"
},
"last_name": {
"type": "string",
"maxLength": 80,
"description": "Applicant Last Name. Required in the CreateRetailAccountApplication operation.",
"example": "Murray"
},
"title": {
"type": "string",
"maxLength": 25,
"description": "Customer Title. Required in the CreateRetailAccountApplication operation.",
"example": "Mr."
},
"gender": {
"type": "string",
"enum": [
"M",
"F"
],
"maxLength": 1,
"description": "Gender of the applicant. Values can include \"M\",\"F\". Required in the CreateRetailAccountApplication operation.",
"example": "M"
},
"date_of_birth": {
"type": "string",
"description": "Date of Birth of the applicant. Required in the CreateRetailAccountApplication operation.",
"example": "1981-04-17",
"format": "date"
},
"nationality": {
"type": "string",
"maxLength": 5,
"description": "Nationality of the applicant. See Country Code values, for allowed list of values. Required in the CreateRetailAccountApplication operation.",
"example": "IN"
},
"second_nationality": {
"type": "string",
"maxLength": 5,
"description": "Second Nationality of the applicant. See Country Code values, for allowed list of values. Required in the CreateRetailAccountApplication operation for applicants with dual nationality.",
"example": "US"
},
"marital_status": {
"type": "string",
"enum": [
"D",
"S",
"M",
"W",
"O"
],
"maxLength": 20,
"description": "Marital Status. Values can include :\n- \"D\" - Divorced,\n- \"S\" - Single,\n- \"M\" - Married,\n- \"W\" - Widowed or \n- \"O\" - Others \n\nRequired in the UpdateRetailAccountApplication operation.\n",
"example": "M"
},
"PEP": {
"type": "string",
"enum": [
"NPEP",
"LPEP",
"FPEP"
],
"description": "Politicially exposed person. Values can include :\n- \"NPEP\" - NOT PEP,\n- \"LPEP\" - LOCAL PEP, \n- \"FPEP\" - FOREIGN PEP\n\nRequired in the CreateRetailAccountApplication operation.\n",
"example": "NPEP"
},
"documents": {
"description": "Identification Documents of the applicant. \n- Document type EMID mandatory in CreateRetailAccountApplication operation.\n- Document type PPT mandatory in UpdateRetailAccountApplication operation.\n- Document type VISA, VISAUID mandatory in UpdateRetailAccountApplication operation for Non GCC Nationals.\n",
"type": "array",
"items": {
"$ref": "#/definitions/documents"
}
},
"addresses": {
"type": "array",
"items": {
"$ref": "#/definitions/addresses"
},
"description": "Addresses of the applicant. Required in the CreateRetailAccountApplication operation."
},
"phones": {
"type": "array",
"items": {
"$ref": "#/definitions/phones"
},
"description": "Phone details of the applicant. Required in the CreateRetailAccountApplication operation."
},
"emails": {
"type": "array",
"items": {
"$ref": "#/definitions/emails"
},
"description": "Emails of the applicant. Required in the CreateRetailAccountApplication operation."
},
"employment": {
"$ref": "#/definitions/employment",
"description": "This aggregate hold the employment details of the applicant. Required in the UpdateRetailAccountApplication operation."
},
"countries_dealing_with": {
"type": "string",
"maxLength": 100,
"description": "List of countries the customer is dealing with. Multiple values to be passed pipe separated. See Country Code values, for allowed list of country codes. The values will be codes and not description. Required in the CreateRetailAccountApplication operation.",
"example": "AE|IN|US"
},
"city_of_birth": {
"type": "string",
"maxLength": 50,
"description": "City of Birth. Required in the UpdateRetailAccountApplication operation.",
"example": "Dubai"
},
"country_of_birth": {
"type": "string",
"maxLength": 5,
"description": "Country of Birth. See Country Code values, for allowed list of values. Required in the UpdateRetailAccountApplication operation.",
"example": "UAE"
},
"report_country_details": {
"type": "string",
"maxLength": 500,
"description": "OECD Report Country details. Required in the CreateRetailAccountApplication operation. See No TIN Reason Code values, for allowed list of Reason Code values when No TIN is available.",
"example": "USA~123445~~remarks| UAE~~No tax number~remarks | IND~ABC12345~Reason B~"
},
"us_relation": {
"type": "string",
"enum": [
"C",
"N",
"O",
"R"
],
"description": "US Relation. Valid values :\n- C - Recalcitrant Customer,\n- N - Not Reportable,\n- O - No,\n- R - Yes-Reportable \n\nRequired in the CreateRetailAccountApplication operation.\n",
"example": "N"
},
"tin_number": {
"type": "string",
"maxLength": 50,
"description": "TIN number available as part of FATCA details. If applicable, must be passed in the CreateRetailAccountApplication operation."
},
"fatca_reason": {
"type": "string",
"maxLength": 200,
"description": "FATCA eligible reason. For multiple FATCA reasons, should be pipe (|) separated. If applicable, must be passed in the CreateRetailAccountApplication operation. See FATCA Reason values, for allowed list of values.",
"example": "CURRENT US ADDR"
},
"fatca_documents_collected": {
"type": "string",
"maxLength": 200,
"description": "FATCA documents collected. Should be pipe (|) separated for multiple documents collected. If applicable, must be passed in the CreateRetailAccountApplication operation. See FATCA Documents Collected, for allowed list of values.",
"example": "ID DOC|LOSS OF NAT CERT|SELF-ATTEST FORM|W8|W9"
},
"fatca_signed_date": {
"type": "string",
"description": "Holds the value of Signed Date, Should be past date. If applicable, must be passed in the CreateRetailAccountApplication operation.",
"format": "date",
"example": "2017-01-01"
},
"income": {
"$ref": "#/definitions/income",
"description": "This aggregate hold the income details of the applicant. Required in the UpdateRetailAccountApplication operation."
}
},
"additionalProperties": false,
"required": [
"documents"
]
}
Holds the details of the documents used to identify a person.
{
"properties": {
"type": {
"type": "string",
"enum": [
"PPT",
"VISA",
"EMID",
"VISAUID"
],
"description": "List of values include - \"PPT\" -Passport - \"VISA\" - Visa File number - \"EMID\" - Emirates ID - \"VISAUID\" - Visa UID number",
"example": "PPT"
},
"number": {
"type": "string",
"maxLength": 100,
"description": "Document Number",
"example": "G5533782"
},
"issue_date": {
"type": "string",
"format": "date",
"maxLength": 10,
"description": "Date of issue of the document. Mandatory for type=VISA & type=PPT.",
"example": "2017-10-30"
},
"expiry_date": {
"type": "string",
"format": "date",
"maxLength": 10,
"description": "Expiry date of the document",
"example": "2019-10-30"
},
"issue_country": {
"type": "string",
"description": "Document issued country",
"example": "IN"
}
},
"additionalProperties": false,
"required": [
"type",
"number",
"expiry_date"
]
}
Holds Address Details of the applicant
{
"properties": {
"type": {
"type": "string",
"enum": [
"RESIDENCE",
"MAILING"
],
"description": "Holds address type. Valid values are \"RESIDENCE\", \"MAILING\".",
"example": "MAILING"
},
"line_1": {
"type": "string",
"maxLength": 50,
"description": "Holds flat number and Building Name.",
"example": "202 Sky Tower"
},
"line_2": {
"type": "string",
"maxLength": 50,
"description": "Holds Street details of the address.",
"example": "23rd Streeet"
},
"po_box": {
"type": "string",
"maxLength": 200,
"description": "P O Box number",
"example": "685"
},
"city": {
"type": "string",
"maxLength": 5,
"description": "Holds city details. Accepts IATA 3-Letter Codes.",
"example": "DXB"
},
"country": {
"type": "string",
"maxLength": 2,
"description": "Holds country details. ISO 2 character Country Codes. See Country Code values, for allowed list of values.",
"example": "AE"
},
"preferred": {
"type": "boolean",
"description": "Holds preferred flag value.(true or false)",
"example": "true"
}
},
"additionalProperties": false,
"required": [
"type",
"line_1",
"city",
"country",
"line_2",
"preferred",
"po_box"
]
}
Holds of the employment details of the applicant
{
"properties": {
"employment_type": {
"type": "string",
"description": "Employment Type of the applicant. See Employment Type values, for allowed list of values.",
"example": "Salaried"
},
"employer_name": {
"type": "string",
"maxLength": 250,
"description": "Employer Name of the applicant. Should have sponsor name when \"employment_type\" is passed as Retired/Housewife/PENSIONER.",
"example": 1
},
"occupation": {
"type": "string",
"maxLength": 100,
"description": "Occupation of the applicant. See Occupation values, for allowed list of values.",
"example": 1
},
"industry_segment_code": {
"type": "string",
"maxLength": 5,
"description": "Segment Code of the Industry. See Industry Segment Code values, for allowed list of values.",
"example": "BFS"
},
"industry_subsegment_code": {
"type": "string",
"maxLength": 5,
"description": "Sub segment Code of the Industry. Required only when applicant's \"employment_type\" is 'Self employed' or 'A' (Salaried & Self-employed). Multiple values can be passed pipe separated. See Industry Sub Segment Code values, for allowed list of values.",
"example": "13|AD|9"
}
},
"additionalProperties": true,
"required": [
"industry_segment_code",
"employment_type",
"employer_name",
"occupation"
]
}
Holds of the income details of the applicant
{
"properties": {
"monthly_income": {
"type": "number",
"minLength": 1,
"maxLength": 15,
"description": "Holds the value of Declared Salary or Monthly Income (AED).",
"example": 50000
},
"expected_monthly_credit_turnover_AED": {
"type": "number",
"minLength": 1,
"maxLength": 20,
"description": "Holds the value of ˜Expected Monthly Credit Turn Over (AED). Decimal(16,3) values allowed.",
"example": 50000
},
"monthly_cash_credit_turnover_percentage": {
"type": "string",
"minLength": 1,
"maxLength": 6,
"description": "Holds the value of Monthly Cash Credit Turnover %. Decimal(3,2) values allowed.",
"example": 25.5
},
"monthly_noncash_credit_turnover_percentage": {
"type": "string",
"minLength": 1,
"maxLength": 6,
"description": "Holds the value of Monthly Non Cash Credit Turnover %. Decimal(3,2) values allowed.",
"example": 70
},
"highest_cash_credit_transaction_AED": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"description": "Holds the value of Highest Cash Credit Transaction (AED). Decimal(16,3) values allowed.",
"example": 5000
},
"highest_noncash_credit_transaction_AED": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"description": "Holds the value of Highest Non Cash Credit Transaction (AED). Decimal(16,3) values allowed.",
"example": 10000
}
},
"additionalProperties": true,
"required": [
"expected_monthly_credit_turnover_AED",
"monthly_cash_credit_turnover_percentage",
"monthly_noncash_credit_turnover_percentage",
"highest_cash_credit_transaction_AED",
"highest_noncash_credit_transaction_AED",
"monthly_income"
]
}
Holds contact details of the applicant
{
"properties": {
"type": {
"type": "string",
"enum": [
"CELLPH1"
],
"description": "Holds Type of the Phone. Valid Values are \"CELLPH1\" - mobile no.,",
"example": "CELLPH1"
},
"country_code": {
"type": "string",
"maxLength": 10,
"description": "Holds the country_code for the phone number",
"example": 971
},
"number": {
"type": "string",
"maxLength": 25,
"description": "Holds the mobile phone number",
"example": "563358985"
}
},
"additionalProperties": false,
"required": [
"type",
"country_code",
"number"
]
}
Holds mail details of the applicant
{
"properties": {
"type": {
"type": "string",
"enum": [
"HOMEEML"
],
"description": "Holds Email Address Type. Valid values - \"HOMEEML\" - Personal email id",
"example": "HOMEEML"
},
"email": {
"type": "string",
"maxLength": 150,
"description": "Holds email address value.",
"example": "abc@email.com"
}
},
"additionalProperties": false,
"required": [
"email",
"type"
]
}
Hold the IBAN account details
{
"properties": {
"IBAN": {
"type": "string",
"maxLength": 23,
"description": "IBAN Number allocated to the customer",
"example": "AE1234562323323"
}
},
"additionalProperties": false,
"required": [
"IBAN"
]
}