API Guide for CIAM – Yakeen Alien Address Info by

Iqama Info Service

Date: 06 Dec 2023

Version: 1.0
 API Integration Document for IAM | Mulesoft

Contents
1. DOCUMENT INFORMATION 3
1.1. DOCUMENT CONTROL 3
2. INTRODUCTION 4
2.1. OBJECTIVE OF THIS DOCUMENT 4
2.2. REFERENCE TO DOCUMENTATION IN ANYPOINT EXCHANGE: 4
2.3. AUDIENCE 4
3. YAKEEN ALIENADDRESSINFOBYIQAMA SERVICE 5
3.1. API SEQUENCE DIAGRAM 5
3.2. SERVICE DESCRIPTION 5
3.3. SERVICE INPUTS 7
3.4. SERVICE OUTPUTS 7
4. MULESOFT HTTP ERROR RESPONSES 8
5. CUSTOM BUSINESS FAULTS 9
5.1. BUSINESS FAULT MESSAGE 9
5.2. SYSTEM FAULT MESSAGE 9
5.3. ERROR CODES 9

RCU | Middleware
 API Integration Document for IAM | Mulesoft

1. Document Information
1.1. Document Control

Version Date Author Change

1.0 07 Dec 2023 Dnyaneshwar Mali Draft Version

1.2 Document Verbs

Name Description
IAM Identity and Access Management
Yakeen Yakeen Services Provide AlienAddressInfoByIqama Information
ELM Simi Government Company – Act as a Service Provider
Mulesoft RCU Integration Platform
Experience API Limited area per each client on Mulesoft platform contains all client APIs
System API Mulesoft internal API act as an interface layer above the service providers
Mulesoft internal API, between Experience api and system api to manage and
Process API orchestrate multi system apis and retrieve the result to the experience api clear
with a little efforts from the experience api layer.
JSON JavaScript Object Notation format style

API Application Programming Interface

XML Extensible Markup Language
SOAP Simple Object Access Protocol
URL Uniform Resource Locator
HTTP Hyper Text Transfer Protocol
TBD To Be Decided

RCU | Middleware
 API Integration Document for IAM | Mulesoft

2. Introduction
2.1. Objective of this document

The purpose of this document is to consolidate details and document the Yakeen
AlienAddressInfoByIqama Information API built for RCU IAM portal, by sending Iqama number
for retrieving the employee basic information from Yakeen.

2.2. Reference to Documentation in Anypoint Exchange:

 Login to the Anypoint Platform: https://eu1.anypoint.mulesoft.com/

 API documentation can be found in Anypoint Exchange

 For RCU IAM portal, refer to e-employee-api from the list of Assets

 Documentation contains all the mentioned endpoints, mock requests, field-level details,
and sample request & response.

2.3. Audience

● API Developer

● Integration Developer

● Technical Lead

● Integration Architect

● QA/UAT team

● Users

RCU | Middleware
 API Integration Document for IAM | Mulesoft

3. Yakeen AlienAddressInfoByIqama Service

3.1. API Sequence Diagram

3.2. Service Description

Title Value
API Description Post request to consolidate details and document the Yakeen
AlienAddressInfoByIqama Information API built for RCU IAM portal, by sending
Address for retrieving the employee basic information from Yakeen:

● Experience api service, it’s a Mulesoft api which act as a interfacing layer to
RCU IAM portal to receive the client requests and manipulating it internally
by the Mulesoft predefined connectors and our custom Mulesoft assets
process and system apis which covered the request needs in the runtime.

● Mulesoft system API catch the request with a JSON format and integrate
with Yakeen alienAddressInfoByIqama Info soap xml service for retrieving
the employee basic information from Yakeen throw the secure public

RCU | Middleware
 API Integration Document for IAM | Mulesoft

network.

● SOAP XML Response from Yakeen AlienAddressInfoByIqama Info service

handled by the Mulesoft system api service and manipulating it before
passing it to Experience API service which prepare the response to the RCU
IAM portal with the JSON format also.
API Endpoint {{e-employee-api}}/v1/yakeen/alienAddressInfoByIqama/retrive

HTTP Method POST

API Calling Type Synchronous Call
API Media Type Application/JSON
API Security Client Id credentials with SLA { client-Id}; {client-secret}
API Credentials TBD Credentials with the target team
API Header Optional Parameters
 correlationId
 channelID
Mandatory Fields
 client-id
 client-secret
API URI parameter NA
API Request Body Sample(1):
{
"addressLanguage": "A",
"dateOfBirth": "12-1405",
"iqamaNumber": "2312536291",
"referenceNumber": "ABC1234"
}

API Query Parameters

NA

API Sample Success {

Responses "AlienAddressInfoByIqamaResult": {
"addressListList": {
"additionalNumber": "7025",
"buildingNumber": "3348",
"city": "‫"الرياض‬,
"district": "‫"العقيق حي‬,
"locationCoordinates": "46.62587150 24.
77903368",
"postCode": "13515",
"streetName": "‫"الناسخ فضائل ابي‬,
"unitNumber": "2"
},
"logId": "1146252536"
}
}

RCU | Middleware
 API Integration Document for IAM | Mulesoft

API Success Status 200

Code
API Sample Error Refer to the Error Responses Section in the Document
Response

3.3. Service Inputs

No Name Description Required
Type
1 addressLanguage Address Language String YES
2 dateOfBirth Date Of Birth 03-1983 String YES
3 iqamaNumber Iqama Number String YES
4 referenceNumber Fixed Number String YES

3.4. Service Outputs

No Name Description Type Required

1 additionalNumber String YES

2 buildingNumber String YES

3 district String YES

4 city String YES

5 locationCoordinates String YES

6 postCode String YES

7 streetName String YES

8 unitNumber String YES

9 logId String YES

RCU | Middleware
 API Integration Document for IAM | Mulesoft

4. Mulesoft HTTP Error Responses

This section describe the HTTP response status codes will be returned from Mulesoft
experience API service based on the error response source.
Title Value
{
"errorCode": 400,
API Sample 400 Error Response "errorType": "Bad request",
"errorMessage": ""
}
{
"errorCode": 401,
API Sample 401 Error Response "errorType": "Unauthorized",
"errorMessage": ""
}
{
"errorCode": 403,
API Sample 403 Error Response "errorType": "Forbidden",
"errorMessage": ""
}
{
"errorCode": 404,
API Sample 404 Error Response "errorType": "Resource not found",
"errorMessage": ""
}
{
"errorCode": 500,
API Sample 500 Error Response "errorType": "Internal Server Error",
"errorMessage": "'"
}
{
"errorCode": 503,
API Sample 503 Error Response "errorType": "Service Unavailable",
"errorMessage": ""
}

RCU | Middleware
 API Integration Document for IAM | Mulesoft

5. Custom Business Faults

This section describe the provider custom business errors which will be handled as a part of the
service failure body response by Mulesoft experience API service, Mulesoft will categorize the
provider custom business errors under the HTTP failure responses codes groups like (400) and
(500) based on the code which will be received from the fault soap xml provider service.

5.1. Business Fault Message

Name Description Type

errorCode Error Code String
errorType Error Type String
errorMessage Error Message String

5.2. System Fault Message

Name Description Type

errorCode Error Code String
errorType Error Type String
errorMessage Error Message String

5.3. Error Codes

Error Code Error Type Error Message

1 Validation Error The iqamaNumber Is Not Found at Yakeen
2 Authentication Error Not Authorized
3 Validation Error (AlienAddressInfoByIqama) DateOfBirth does not match records
100 System Error An Error Occurred while processing your request. Please try again later

RCU | Middleware