---
swagger: "2.0"
info:
  title: Partner Retail Account Applications API
  version: 1.3.0
  x-ibm-name: partner-retail-account-applications-api
  description: "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.\n\nThe on-boarding process invloves
    three stages during which the Partner Retail Account Application API is invoked
    by the Partner:\n\n  - Stage 1 : The applicant enters his/her basic details and
    uploads scanned copy of the Emirates ID on the Partner App\n  - 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\n
    \ - Stage 3 : The applicant provides additional KYC documents/details if requested
    at the end of Stage 2 by RAKBank Compliance Team\n\n\n\tVersion 1.1.0\n\n  - 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.\n  - UpdateRetailAccountApplicationStatus can be used only
    when status needs to be updated for eg. in case of rejections.\n  - "demographic"
    property has been renamed to "countries_dealing_with". Similarly a few
    fatca related fields have been renamed.\n\n\n\tVersion 1.1.1\n\n  - Added field
    employer_name under employment. Corrected length of field IBAN to 23.\n  - Added
    "income" under applicant.\n  - Corrected Valid values for employment_type.\n
    \ - New documents.type "VISAUID" added, mandatory for UpdateRetailAccountApplication
    operation.\n\n\n\tVersion 1.2.0\n\n  - 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.\n  - Added fields "remarks" under application_status.
    Remarks can be provided when passing status as 'ADDITIONAL_COMPLIANCE_INFO_PROVIDED'
    in UpdateRetailAccountApplicationStatus operation.\n  - 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.\n\n\n\tVersion 1.3.0\n\n  -
    Added "second_nationality" which is mandatory for customers with dual
    nationality.\n  - Added "monthly_income" under income.\n  - Additional
    "employment_type" values added for dependants.\n  - "employer_name"
    should have sponsor name when "employment_type" is passed as Retired/Housewife/PENSIONER.\n
    \ - Document type VISA, VISAUID are not required to be passed in case of GCC Nationals.\n
    \ - "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)."
  contact:
    email: apideveloper@rakbank.ae
    name: API Developer
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: application
    scopes:
      retail_account_applications: ""
    tokenUrl: https://sandboxapi.rakbank.ae/rb/api/v1/partner_auth/token
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientIdHeader: []
  oauth:
  - retail_account_applications
x-ibm-configuration:
  testable: false
  enforced: true
  phase: realized
paths:
  /retail/account_applications:
    post:
      responses:
        201:
          description: Created
          schema:
            $ref: '#/definitions/retail_account_applications_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      tags: []
      summary: This is used to submit an application for a new account opening for
        a new retail customer.
      operationId: CreateRetailAccountApplication
      parameters:
      - name: retail_account_applications
        required: true
        in: body
        schema:
          $ref: '#/definitions/retail_account_applications'
        description: All the customer and account details for creating a retail account
          application
  /retail/account_applications/{account_application_id}:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/retail_account_applications_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      tags: []
      summary: This is used to update KYC details of an applicant after completion
        of document verification on your end.
      operationId: UpdateRetailAccountApplication
      parameters:
      - name: account_application_id
        required: true
        in: path
        type: string
        maxLength: 30
        description: Application Id returned in the CreateRetailAccountApplication
          operation response.
      - name: retail_account_applications
        required: true
        in: body
        schema:
          $ref: '#/definitions/retail_account_applications'
        description: additional details of the application
  /retail/account_applications/{account_application_id}/application_status:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/application_status'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      tags: []
      summary: 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.
      operationId: UpdateRetailAccountApplicationStatus
      parameters:
      - name: account_application_id
        required: true
        in: path
        type: string
        maxLength: 30
        description: Application Id returned in the CreateRetailAccountApplication
          operation response.
      - name: application_status
        required: true
        in: body
        schema:
          $ref: '#/definitions/application_status'
        description: status of the application
    parameters:
    - name: MsgId
      type: string
      maxLength: 50
      required: true
      in: header
      description: Unique Id sent by client. Value should be a unique identifier of
        the request in UUID format.
definitions:
  error_response:
    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
    description: Response in case of error
    required:
    - response_code
    - response_message
    - status
  application_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
  retail_account_applications:
    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
  retail_account_applications_response:
    description: 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
  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 <a href=/sb/api/reference-data#country-codes-retail-account-appln>Country
          Code values</a>, 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 <a href=/sb/api/reference-data#country-codes-retail-account-appln>Country
          Code values</a>, 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 <a href=/sb/api/reference-data#country-codes-retail-account-appln>Country
          Code values</a>, 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 <a href=/sb/api/reference-data#country-codes-retail-account-appln>Country
          Code values</a>, 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 <a href=/sb/api/reference-data#no-TIN-reason>No TIN Reason
          Code values</a>, 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 <a href=/sb/api/reference-data#fatca-reason>FATCA Reason
          values</a>, 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 <a href=/sb/api/reference-data#fatca-docs-collected>FATCA
          Documents Collected</a>, 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
    description: Holds the details of the Applicant
    required:
    - documents
  documents:
    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
    description: Holds the details of the documents used to identify a person.
    required:
    - type
    - number
    - expiry_date
  addresses:
    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 <a
          href=/sb/api/reference-data#country-codes-retail-account-appln>Country Code
          values</a>, for allowed list of values.
        example: AE
      preferred:
        type: boolean
        description: Holds preferred flag value.(true or false)
        example: "true"
    additionalProperties: false
    description: Holds  Address Details of the applicant
    required:
    - type
    - line_1
    - city
    - country
    - line_2
    - preferred
    - po_box
  employment:
    properties:
      employment_type:
        type: string
        description: Employment Type of the applicant. See <a href=/sb/api/reference-data#employment-type>Employment
          Type values</a>, 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 <a href=/sb/api/reference-data#occupation>Occupation
          values</a>, for allowed list of values.
        example: 1
      industry_segment_code:
        type: string
        maxLength: 5
        description: Segment Code of the Industry. See <a href=/sb/api/reference-data#industry-segment>Industry
          Segment Code values</a>, 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 <a href=/sb/api/reference-data#industry-subsegment>Industry
          Sub Segment Code values</a>, for allowed list of values.
        example: 13|AD|9
    additionalProperties: true
    description: Holds of the employment details of the applicant
    required:
    - industry_segment_code
    - employment_type
    - employer_name
    - occupation
  income:
    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.500000
      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
    description: Holds of the income details of the applicant
    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
  phones:
    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
    description: Holds contact details of the applicant
    required:
    - type
    - country_code
    - number
  emails:
    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
    description: Holds mail details of the applicant
    required:
    - email
    - type
  account:
    properties:
      IBAN:
        type: string
        maxLength: 23
        description: IBAN Number allocated to the customer
        example: AE1234562323323
    additionalProperties: false
    required:
    - IBAN
    description: Hold the IBAN account details
tags: []
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...