Classification: Restricted

Classification: Restricted

Classification: Restricted

API Integration

< SimahPro Direct >

Version <0.2>
31- August - 2021
IT Development

ABR for < Credit Report Enhancements > 1

 Classification: Restricted

Classification: Restricted

Revision History
Version Date Description Author(s)
0.1 11/04/2021 Draft Abuzieneh
0.2 31/08/2021

Contents
REVISION HISTORY ............................................................................................................................................................................2
1. INTRODUCTION .........................................................................................................................................................................2
WELCOME TO SIMAHPRO DIRECT, YOUR NEW CHANNEL TO EXPLORE ALL THE BENEFITS SIMAH CAN OFFER TO IT MEMBERS .............................................. 2
2. INTEGRATION ............................................................................................................................................................................3
3. AUTHENTICATION .....................................................................................................................................................................3
4. MEMBER REFERENCE NUMBER MAPPING .................................................................................................................................4
5. SERVICES ...................................................................................................................................................................................4
6. REQUEST ...................................................................................................................................................................................4
7. RESPONSE .................................................................................................................................................................................5
8. SECURITY ..................................................................................................................................................................................7
9. ERROR MESSAGES .....................................................................................................................................................................7

1. Introduction
Welcome to Simahpro direct, your new channel to explore all the benefits Simah can
offer to it members

https://spapiuat.simah.com/swagger/index.html

ABR for < Credit Report Enhancements > 2

Classification: Restricted

Classification: Restricted

2. Integration
For members to able to establish a connection between their system and Simah API, member has to provide a public
static IP to be whitelisted by Simah.

The connection would be consumed over SSL version 3.0

Members should obtain user name, password and URL for required environment in order to setup a connection with
Simah. Operation department at Simah will provide these information.

3. Authentication
The service authentication is based on Oauth 2.0 JWT token. In order to issue token please initiate the below request in
your corresponding programing language. The response will contain the JWT token if the authentication is valid,
otherwise the account will be blocked for 15 minutes after 3 failed attempts.

In case of successful response the subsequent requests Simah services will require the token to be passed as a bearer
authentication mechanism.

CURL Request:

POST /api/v1/Identity/login

"username": [username]

"password":[password]

CURL Response

"isSuccess": true,

"data": {

"token": "{token}"

},

"message": null

Token will be valid for a cetin period of time. Once expired , error number 401 will be returned and member need to
reissue the token

ABR for < Credit Report Enhancements > 3

 Classification: Restricted

Classification: Restricted

4. Member Reference Number mapping

Member reference number, as its name suggests, will be the member reference for their usage tracking in the future.

Members have two options:

1- Not to send reference number and rely on Simah default reference number which has the following format

2 0 0 1 1 1 E Q 0 1 0 1 2 1 1 5 3 3 1 2 3 4

Application Member Service Date (ddmmyy) Time Random

Code Code Code (hhmm) Number

2- To send their own reference number using any format they finds fit for them.
Allowed format: any number with a minimum length of 1 and max length of 42 digit, only “_” allowed as special
character.

If member choose to go with option 2, Simah will still prefix the reference number with the following code 20+[4 digit
member code] + [ 2 digit service code] when returning the response to the customer

For example, if member “Alpha” with member code = 777 tries to do enquires then

Service Reference simah receives from member in request Reference simah return to member in response
enquiry MemberReferenceNumber 200xxxEQMemberReferenceNumber
enquiry 112233445566 200777EQ112233445566

5. Services

Please retrieve https://spapiuat.simah.com/swagger/index.html for list of services

6. Request
A sample request schema can be found under each type of request e.g. For Review enquiry:

ABR for < Credit Report Enhancements > 4

Classification: Restricted

Classification: Restricted

7. Response
A sample response schema can be found under each type of request under the 200 code response e.g. For Review
enquiry and the description for the properties are available by browsing the model:

ABR for < Credit Report Enhancements > 5

 Classification: Restricted

Classification: Restricted

Lookups:
In order to do

Loookup Name Link

ID Types /api/v1/Lookup/lookup/getidtypes
Get all lookup values for the id types

Products /api/v1/Lookup/lookup/getallproducts
Get all lookup values for the products that are assigned to the member

Employer Types /api/v1/Lookup/lookup/getemployertypes

Get all lookup values for the Employer types.

Nationalities /api/v1/Lookup/lookup/nationalities
Get all lookup values for the nationalities

Marital Status /api/v1/Lookup/lookup/maritalstatus

Get all lookup values for the marital status

Applicant Types /api/v1/Lookup/lookup/applicanttypes

Get all lookup values for the applicant types

Contact Types /api/v1/Lookup/lookup/contacttypes

Get all lookup values for the contact types

Country Codes
/api/v1/Lookup/lookup/countrycodes
Get all lookup values for the country codes

ABR for < Credit Report Enhancements > 6

Classification: Restricted

Classification: Restricted

Address Types /api/v1/Lookup/lookup/addresstypes

Get all lookup values for the address types

Cities /api/v1/Lookup/lookup/cities
Get all lookup values for the cities

Business Types /api/v1/Lookup/lookup/businesstypes

Get all lookup values for the business types

Processing Types /api/v1/Lookup/lookup/processingtypes

Get all lookup values for the business types

Reason Codes /api/v1/Lookup/lookup/reasoncodes

Get all lookup values for the business types

Employer Statuses /api/v1/Lookup/lookup/employerstatuses

Get all lookup values for the employer status types

Declaration Types /api/v1/Lookup/lookup/declarationtypes

Get all lookup values for the declaration types

Home Ownerships /api/v1/Lookup/lookup/homeownerships

Get all lookup values for the home ownerships

Residence Cities /api/v1/Lookup/lookup/residencecities

Get all lookup values for the residence cities

8. Security

The payload data traffic is encrypted using TLS encryption with rate limiting to prevent denial of service attacks. The
principle of least privilege is applied across the API to grant only the minimum required privileges.

The API uses strong authentication and authorization mechanism with authorization mechanism of OAuth 2.0 and
OpenID Connect.

9. Error Messages

Code Description

ABR for < Credit Report Enhancements > 7

 Classification: Restricted

Classification: Restricted

GEN_000 Please Call SIMAH for support

GEN_006 Unable to Process the Request. Please try again after sometime
GEN_007 You don't have access to this service
CS_ENQ_002 CR/ID entered is not valid
CS_ENQ_003 The report is not obtainable at the moment, please try another time or try other
reports
C_NQ_001 The report generated successfully
C_NQ_002 There was an error in generating report
C_NQ_003 Product supplied is invalid
C_NQ_004 The Id type is invalid
C_NQ_005 Marital Status is invalid
C_NQ_006 Nationality is invalid
C_NQ_007 Address type is invalid
C_NQ_008 City is invalid
C_NQ_009 Contact type is invalid
C_NQ_010 Occupation sector is invalid
C_NQ_011 Occupation address type is invalid
C_NQ_012 Occupation city is invalid
C_NQ_013 Consent is required
C_NQ_014 Duplicate applicants found
C_NQ_017 Sector supplied is invalid
C_NQ_018 City supplied is invalid
C_NQ_019 Member authentication is invalid
C_NQ_020 Saving customer failed
C_NQ_022 The Legal type is invalid
C_NQ_028 Country is invalid
C_NQ_041 Member ID not known to bureau
C_NQ_040 Member/User not authorised to Service/Action
C_NQ_039 Non-Arabic characters in Arabic Tag
C_NQ_044 Date of birth month is not between 1 and 12
C_NQ_045 Consumer is less than 10 years old
C_NQ_046 Date of birth is not a valid date
C_NQ_047 Gender not valid code
C_NQ_048 ID Type not valid code
C_NQ_049 Invalid ID Number
C_NQ_050 Combination of the ID Type and Nationality not valid
C_NQ_052 ID type and ID number supplied does not exist in the system
C_NQ_053 Invalid ID Number supplied
S_NQ_002 Invalid employer type
S_NQ_001 Invalid applicant type
S_NQ_003 Id Expiry Date should be in future
S_NQ_004 Cr Number is mandatory in case of self-employment
S_NQ_005 Area Code is required if contact type is not mobile
S_NQ_006 Invalid mobile number
S_NQ_007 Invalid Phone number
S_NQ_008 Invalid Country Code
S_NQ_009 Extension and Area code should be greater than 0
S_NQ_010 Extension min length=1 & MaxLength=5

ABR for < Credit Report Enhancements > 8

Classification: Restricted

Classification: Restricted

S_NQ_011 Invalid reason code

ABR for < Credit Report Enhancements > 9