IHC INSURANCE COMPANY

INTEGRATION GUIDE
COMPREHENSIVE LEASED VEHICLES
V1.2

24 SEPTEMBER 2020

IHC– Auto Lease Integration Guide – Confidential Page | 1

Copyright Acknowledgement
IHC Integration Guide (this document, “the document”, “document”) inclusive of its wordings, illustrations, graphs, tables, and software code snippets
are under copyright protection and are the property of Insurance House Company. No part of this document may be reproduced, distributed, or
transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written
permission of IHC.

For permission requests, write to us in our address below.

Confidentiality Statement
This document has been presented and might be later shared via email with confidentiality being restricted to authorized Insurance Company staff. Prior
explicit formal written approval from IHC is required before viewing, using, altering, distributing, and/or copying this document by any person/entity not
explicitly authorized by IHC.

The use of this document weather in its draft or final format is strictly confidential. IHC reserve the right to take all the necessary legal actions against
any unauthorized party that misuses, copies, alters or distributes this document without prior formal written permission.

IHC™ is a trademark of Insurance House Company Information Technologies. Registration pending by the Ministry of Commerce and Investment of the Kingdom of Saudi Arabia. This document inclusive of its
figures and artifacts are the Copyright property of Insurance House Company.

Copyright © 2020 Insurance House Company, llc. All rights reserved. Insurance House Company is located at King Abdullah Branch Road, Riyadh 12362-6394, Saudi Arabia. [email protected]

NO07880

IHC– Auto Lease Integration Guide – Confidential Page | 2

Contents
Copyright Acknowledgement ............................................................................................................................................. 1
Confidentiality Statement .................................................................................................................................................. 2
Introduction ............................................................................................................................................................ 6
Intended Audience ................................................................................................................................................. 6
Implementation Overview ..................................................................................................................................... 6
3.1 Data Exchange Process Flow ....................................................................................................................................................................................... 7
3.2 Insurance Company Onboard Process ........................................................................................................................................................................ 8
3.3 API Overview -Sequence Diagram............................................................................................................................................................................... 9
Technical Guide .................................................................................................................................................... 10
4.1 Web API Integration Prerequisite ............................................................................................................................................................................. 10
4.2 Communication Interface ......................................................................................................................................................................................... 10
4.3 Live & UAT Environments.......................................................................................................................................................................................... 10
4.4 Request and Response format .................................................................................................................................................................................. 10
4.5 Field Type Abbreviations ........................................................................................................................................................................................... 11
4.6 Definitions, Acronyms, and Abbreviations ................................................................................................................................................................ 11
4.7 Authentication Mechanism ....................................................................................................................................................................................... 11
4.8 Insurance Company & IHC Web API Methods .......................................................................................................................................................... 12
Method Workflow ................................................................................................................................................. 15
5.1 “Quote” Method ....................................................................................................................................................................................................... 15
Sequence Diagram: ........................................................................................................................................................................................................... 15
Request Parameters For “Quote” Method: ...................................................................................................................................................................... 15
Response Parameters For “Quote” Method: .................................................................................................................................................................... 23
5.2 “Policy” Method ........................................................................................................................................................................................................ 28

IHC– Auto Lease Integration Guide – Confidential Page | 3

 Sequence Diagram: ........................................................................................................................................................................................................... 28
Request Parameters for “Policy” Method:........................................................................................................................................................................ 29
Response Parameters for “Policy” Method: ..................................................................................................................................................................... 30
5.3 “PolicyIssue” Method ................................................................................................................................................................................................ 31
Sequence Diagram ............................................................................................................................................................................................................ 31
Request Parameters for “PolicyIssue” Method: ............................................................................................................................................................... 32
Response Parameters for “PolicyIssue” Method .............................................................................................................................................................. 36
5.4 “UpdatePolicyNumber” Method ............................................................................................................................................................................... 37
Sequence Diagram ............................................................................................................................................................................................................ 37
Request Parameters for UpdatePolicyNumber:................................................................................................................................................................ 38
Response Parameters for UpdatePolicyNumber: ............................................................................................................................................................. 39
5.5 “VehicleIDUpdate” Method ...................................................................................................................................................................................... 40
Sequence Diagram ............................................................................................................................................................................................................ 40
Request Parameters for VehicleIDUpdate: ....................................................................................................................................................................... 40
Response Parameters for VehicleIDUpdate: ..................................................................................................................................................................... 41
5.6 “IcUpdatePolicy” Method ......................................................................................................................................................................................... 43
Sequence Diagram: ........................................................................................................................................................................................................... 43
Request Parameters for “IcUpdatePolicy” Method: ......................................................................................................................................................... 44
Response Parameters for “IcUpdatePolicy” Method:....................................................................................................................................................... 46
5.7 “AddFeature” Method .............................................................................................................................................................................................. 47
Sequence Diagram ............................................................................................................................................................................................................ 47
Request Parameters for “QueryFeature” Method:........................................................................................................................................................... 48
Response Parameters for “QueryFeature” Method: ........................................................................................................................................................ 49
Request Parameters for “PurchaseFeature” Method: ...................................................................................................................................................... 51
Response Parameters for “PurchaseFeature” Method: ................................................................................................................................................... 52
5.8 “AddDriver” Method ................................................................................................................................................................................................. 53

IHC– Auto Lease Integration Guide – Confidential Page | 4

 Sequence Diagram ............................................................................................................................................................................................................ 53
Request Parameters for “AddDriver” Method:................................................................................................................................................................. 53
Response Parameters for “AddDriver” Method: .............................................................................................................................................................. 57
Request Parameters for “ConfirmAddDriver” Method:.................................................................................................................................................... 59
Response Parameters for “ConfirmAddDriver” Method: ................................................................................................................................................. 60
5.9 “CancelPolicy” Method ............................................................................................................................................................................................. 61
Sequence Diagram ............................................................................................................................................................................................................ 61
Request Parameters for “CancelPolicy” Method .............................................................................................................................................................. 61
Response Parameters for “CancelPolicy” Method............................................................................................................................................................ 63
5.10 “IcCancelPolicy” Method........................................................................................................................................................................................... 64
Sequence Diagram ............................................................................................................................................................................................................ 64
Request Parameters for “IcCancelPolicy” Method: .......................................................................................................................................................... 64
Response Parameters for “IcCancelPolicy” Method: ........................................................................................................................................................ 66
5.11 After Error codes ....................................................................................................................................................................................................... 67
5.12 Error response fields ................................................................................................................................................................................................. 68
5.13 Error codes (HTTP - 400) ........................................................................................................................................................................................... 69

IHC– Auto Lease Integration Guide – Confidential Page | 5

 Introduction
IHC Online Policy Aggregator is a service that enables the lessor to view and compare insurance policies provided by different insurance
companies simultaneously.

This document explains how Insurance Companies can design & develop a Web API to integrate with the IHC Online Policy Aggregator for Auto
Lease Comprehensive Insurance.

Intended Audience
This document has been created for the Insurance Company developers and technical teams who will integrate with IHC Online Policy
Aggregator for Comprehensive Insurance.

Implementation Overview
IHC Portal has an Online Policy Aggregator which uses the Insurance Company’s API to request and receive quotes and issue policies.

IHC will send request(s) to Insurance Company API depending on how many comprehensive products they have registered with IHC. These
requests will contain the lessee, vehicle details and other important details as well.

In response, the Insurance Company replies to IHC with a quote along with the deductible choices, its Net prices, features, and premium features
prices available for that product. IHC portal then presents all insurance companies quotes to the lessor employee.

Once the customer selects a policy quote, they will be asked to issue a draft policy. The Insurance Company should acknowledge the receipt of
the policy request from IHC and keep the quote active with the chosen deductible, premium and features. Once the Leasing contract is signed,
the lessor employee issues the policy, the Insurance company should acknowledge the issuance request sent by IHC.

IHC maintain a grace period for the Quotation, these are used to make sure that Quotes offered to the customer are only available for enough
time as per the business needs.

Note:
In case the customer did not issue any policy and the Quotation Grace Period expired, a new request for quotation is going to be generated from
IHC, and no issuance can be requested for the expired quotes.

As a final step, once the insurance company uploaded successfully purchased policy to Najm system, Insurance Company will call IHC API to send
Najm’s reference number for that policy.

IHC– Auto Lease Integration Guide – Confidential Page | 6

3.1 Data Exchange Process Flow
The Following steps outline the high-level overview of process workflow for each comprehensive issue request to insurance company, and per
each comprehensive product that the insurance company has:

1. Lessor Employee enters required Lessee and vehicle information into IHC portal and IHC system verifies some customer and vehicle details
with Saudi Arabia NIC (National Information Center).
2. IHC will inquire from Najm about the policy holder NCD records.
3. IHC system sends the customer, driver, vehicle, and comprehensive details to all subscribed Insurance Companies in order to get quotes and
the number of requests will depend on the number of the insurance company’s comprehensive products registered with IHC.
4. Insurance company authorizes the API quote request from IHC.
5. Insurance company analyzes and processes IHC quote request and provides a quote for each comprehensive product they have configured
with IHC, the insurance company responses will contain the deductible choices, net prices, and premium features.
6. Once all insurance companies have responded with their quotes, all the received quotes are displayed to the employee.
7. The employee will select the suitable quotation, chose the deductible amount, the additional premium feature as he will agree with the
customer and request to issue policy.
8. IHC sends a request to the respective insurance company to keep this quote active till sending the request for issuance.
9. When the customer will sign the leasing contract, then the Lessor employee will send request to issue the policy.
10. The Insurance company analyzes the request and provides the policy details in response.
11. Once the insurance company uploaded the policy successfully to Najm system, Insurance Company then will send to IHC API “Najm
reference number (VehicleIDUpdate)”.
12. At this point the policy is active from the policy effective date.
13. After the policy has been purchased, it can be updated, modified, or cancelled (see following two sections for flows).

Note:

- IHC is offering (ICUpdatePolicy)for insurance company to Update previous purchased policies. This is happening when for example the lessee
updated his Plate number, or Mobile number for that purchased policy via IHC.

- IHC is offering (AddDriver) and (AddFeature) for insurance company to add multiple drivers and features respectively.

- IHC is offering API (CancelPolicy) to Cancel (delete) previous purchased policies. This is happening when for example the leasing contract is
terminated.

IHC– Auto Lease Integration Guide – Confidential Page | 7

3.2 Insurance Company Onboard Process
▪ Insurance Company contact IHC to integrate with the IHC Portal.
▪ IHC creates users in the portal for the Insurance Company.
▪ IHC provides API integration guidelines to Insurance Company.
▪ Insurance Company develops API for Test environment and Live environment and provides the authentication and URL details to IHC.
▪ IHC configures Test and Live environment API details in system with following.
▪ Test Environment:
1. API URL (URLs will be given and specified below on each method)
2. Username
3. Password
▪ Live Environment:
4. API URL (URLs will be given and specified below on each method)
5. Username
6. Password

▪ IHC tests the Insurance Companies API and confirms the integration

IHC– Auto Lease Integration Guide – Confidential Page | 8

3.3 API Overview -Sequence Diagram
Sequence of the API calls [Overview]

IHC– Auto Lease Integration Guide – Confidential Page | 9

 Technical Guide
4.1 Web API Integration Prerequisite
A successful integration requires that the client’s IT personnel have basic knowledge of the following areas:

▪ Web API
▪ Data exchange workflows
▪ Basic programming skills
▪ Business process management
▪ Workflow concepts, design, and implementation
▪ JSON

4.2 Communication Interface

▪ Web API (HTTPS Protocol)

4.3 Live & UAT Environments

Live & Test environments shall be prepared by Insurance company system and IHC system as well with the following details:

• Test Environment:
1. API URL (URLs will be given and specified below on each method)
2. Username
3. Password
• Live Environment:
1. API URL (URLs will be given and specified below on each method)
2. Username
3. Password

4.4 Request and Response format

IHC and Insurance Company will communicate in standard JSON (JavaScript Object Notation) format.

JSON format references:

https://www.w3schools.com/js/js_json_intro.asp

IHC– Auto Lease Integration Guide – Confidential Page | 10

4.5 Field Type Abbreviations
Field Type Description
Alpha This type of fields only accepts alphabetical characters (Arabic & English); i.e.
from (A-a) to (Z-z).

Alphanumeric This field contains a combination of alphabetic (A-a) to (Z-z), numeric values (0-
9), and special characters based on the parameter specifications.

Numeric This field type represents numeric values; only characters in the range from 0 to
9.

Boolean This field type represents Boolean value; in terms of true or false.

Array This will be list of a specific object array to be passed via JSON. Integer arrays
are also used in our methods.
Timestamp Date-time field wherein date time in universal format can be passed.
For example: 2016-05-15 19:15:10

4.6 Definitions, Acronyms, and Abbreviations

Definitions, Abb. Description
IC Insurance Company

Quotation Grace Period The time given and agreed between Insurance company and IHC. So, the
insurance company will give IHC a period (30 days) for shared quotation.
In case IHC send to IC success policy issue notification within this period
then IC will issue that policy. However, if the grace period has elapsed
without IHC notification, then IC can cancel this quotation.

4.7 Authentication Mechanism

Basic Authentication:
Header Parameter Name: Authorization

Following are the Authentication parameters (as provided with API URL at the time of on board process):

IHC– Auto Lease Integration Guide – Confidential Page | 11

 ▪ Username
▪ Password
References:
https://en.wikipedia.org/wiki/Basic_access_authentication
http://www.asp.net/web-api/overview/security/basic-authentication

4.8 Insurance Company & IHC Web API Methods

Methods Description API Location

Quote IHC will post a request to IC web API to this method to IC

get quotes. IC will validate the request and provide
response (quote details) to IHC.

Policy IHC will post a request to IC web API to this method to IC

get a draft policy from IC. IC will validate the request
and provide a response with draft policy details to IHC.
The IC shall keep the quote active upon receiving this
request.
PolicyIssue IHC will use this method to notify IC with policy IC
issuance.
When Lessor proceeds to issue the policy, IHC system
will use this method to Notify and pass additional
parameters to insurance company.

UpdatePolicyNumber IC uses this method once they receive a PolicyIssue IHC

from IHC and wish to update the IHC policy details with
the correct policy number that was uploaded to NAJM
VehicleIDUpdate IC uses this method to send Najm VehicleID number to IHC
IHC after successful upload the policy to National
Information Center (NIC) via Najm (this is only for
purchased policies).
ICUpdatePolicy In case Lessee has updated (Plate number, Mobile IC
number) of already purchased policy that has been
purchased from IHC, IHC informs IC accordingly and
immediately by using this method to update these

IHC– Auto Lease Integration Guide – Confidential Page | 12

 details through the API. The Lessor employee will be
able to update the policy information through IHC if
this change will not affect the price. IHC will do all the
required verification for the information provided by
the client before requesting the method.
AddFeature This function breaks down to 2 methods: IC
1. QueryFeature
IHC will post this method to IC to enquiry for
the available features for the purchased policy.
2. PurchaseFeature
IHC will post this method to IC to notify it of
the selected features that will be added to the
policy.
AddDriver This function breaks down to 2 methods: IC
1. AddDriver
IHC will post this method to IC with additional
driver(s) details to inquiry about the additional
charge.
2. ConfirmAddDriver
IHC will post this method to IC to notify it of
adding the driver(s).
CancelPolicy In case IC has cancelled or revoked a policy that has IHC
been purchased from IHC earlier, IC SHOULD inform
IHC accordingly and immediately by using this method
to cancel a policy through the IHC API.
IcCancelPolicy IHC will post a request to IC web API if Lessor employee IC
initiated a cancellation request via IHC portal. IC
validates the request and acknowledges policy
cancellation.

Important Notes:
- Insurance companies can implement their services in any language they want and in any method, they like (Web-API or web-service (WCF), as
long as they follow below instructions.

IHC– Auto Lease Integration Guide – Confidential Page | 13

 - The URL of service should be in secure protocol (HTTPS). (HTTP) URL will not be accepted (for UAT purpose could be allowed). Web Service
with Dual authentication not allowed.

- Insurance company must implement basic authentication to secure their service.

- Method names, Parameters, Request and Response formats MUST be followed exactly according to this Integration Guide Document and
supported documents or files.

IHC– Auto Lease Integration Guide – Confidential Page | 14

 Method Workflow
5.1 “Quote” Method
IHC will post a request to this IC web API method to get quotes from ICs. Each IC will validate the request and provide response (quotation) to
IHC. See the Sequence diagram for “Quote” method on Figure 1.

Hint: The lessee information is shared in quote request and response as standalone parameters, if any other additional driver exists, his
information will be shared in the ‘DriverDetails’ array.

Sequence Diagram:

Figure 1: Sequence diagram for "Quote" Method

Request Parameters For “Quote” Method:

Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
RequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each Quote request from IHC system to IC API will have
Unique Request Reference number generated by IHC
system.

IHC– Auto Lease Integration Guide – Confidential Page | 15

 InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by IHC. This code is Not
Smallint changeable. Each insurance company will have its own and
fixed Code.
Details
LessorNameEN Alpha(150) Auto Leasing YES User Lessor company name in English
input
LessorID Numeric(10) 7005454545 YES User Lessor/ Leasing Company MOI Number (70XXXXXXXX)
input
LessorBranch Numeric(10) 123 YES IHC Lessor branch code
LessorNationalAddress JSON Array YES Elm Lessor’s National Address. Refer to “NationalAddress” for
more details.
IsRenewal Boolean False YES IHC “True”: means Lessee already have an active policy or
expired policy (within 30 days) for that insurance company
“False”: it is Not a renewal
PolicyNumber Alphanumeric(15) PN7384758327384 If IsRenewal: IHC There should be an active policy number in this case, and it
true, then Yes. should be sent here.
else, NO
PurposeofVehicleUseID Numeric(2) 2 YES User Purpose of using the vehicle. Refer to PurposeOfVehicle
tinyint input master table for supported values.
Cylinders Numeric(3) 6 NO IHC Vehicle engine cylinders capacity
SmallInt
VehicleMileage Numeric(6) 50000 No IHC Vehicle Mileage in KM (kilometers)
VehicleExpectedMileageYear Numeric(6) 25000 No User Vehicle Expected Mileage per Year in KM (Kilometers)
input
VehicleEngineSizeCC Numeric(5,3) 1.600 No IHC Vehicle Engine Size in Litters (1.6Liter == 1600 CC)
Float

VehicleTransmission Numeric(2) 1 YES User 1 : Automatic

tinyint input 2 : Manual Transmission
VehicleNightParking Numeric(2) Garage YES User Where Vehicle Parked at Night
tinyint input 1 : Street
2: HomeLane
3 : Garage
VehicleCapacity Numeric(2) 5 NO IHC Vehicle Seat(s) Capacity
VehicleMakeCodeNIC Numeric(5) 301 YES IHC IHC will send Make Code based on ELM Vehicle Make code
SmallInt (e.g., ‫تويوتا‬, ‫هوندا‬, etc.). Refer to VehicleMake master table
for supported values.
VehicleMakeTextNIC Alphanumeric(25) ‫تويوتا‬ YES IHC IHC will send Model as a text based on ELM Vehicle Model
(e.g., ‫تويوتا‬, ‫هوندا‬, etc.). Refer to VehicleMake master table
for supported values.

IHC– Auto Lease Integration Guide – Confidential Page | 16

 VehicleMakeCodeIHC Numeric(4) 16 YES IHC Vehicle Make code (e.g., TOYOTA, FORD, etc.).Refer to
SmallInt VehicleMake master table for supported values.
VehicleModelCodeNIC Numeric(5) 301 YES IHC IHC will send Model Code based on ELM Vehicle Model code
SmallInt (e.g., Camry, Avalon, etc.). Refer to VehicleModel master
table for supported values.
VehicleModelTextNIC Alphanumeric(25) ‫كامري‬ YES IHC IHC will send Model as a text based on ELM Vehicle Model
(e.g., ‫كامري‬, Avalon, etc.).Refer to VehicleModel master
table for supported values.
VehicleModelCodeIHC Numeric(5) 110 YES IHC IHC will send IHC Model Code. Refer to VehicleModel
SmallInt master table for supported values.
ManufactureYear Numeric(4) 2010 YES User Vehicle manufacture year.
input
VehicleColorCode Numeric(3) 19 YES User Vehicle Color code (e.g., Black, White, etc.).
SmallInt input Refer to VehicleColor master table for supported values.
VehicleModifications Alphanumeric(150) Extra Metal No User Vehicle extra modification as per customer entry
Pumper input
VehicleSumInsured Numeric(6) 999999 YES User Vehicle Value. This information is taken from IHC
input System/User Entry
RepairMethod SmallInt 1 YES User Refer to RepairMethod master table for supported values.
input
CustomizedParameter JSON Array NO IHC Custom parameters array in case of additional parameters
required. Refer to “CustomizedParameter” for further
details.
LesseeID Numeric(10) XXXX943082 YES User The Lessee ID (National ID Number, Iqama ID Number, or
input Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
FullName Alpha(150) ‫خالد أحمد‬ YES Elm The Lessee Name
ArabicFirstName Alpha(150) ‫سالم‬ YES Elm Lessee fist Name in Arabic
(if English isn’t
sent )
ArabicMiddleName Alpha(150) ‫سعود‬ Elm Lessee middle Name in Arabic
ArabicLastName Alpha(150) ‫بدر‬ Elm Lessee last Name in Arabic
EnglishFirstName Alpha(150) Salem YES Elm Lessee fist Name in English
(if Arabic isn’t
sent
)
EnglishMiddleName Alpha(150) Saud Elm Lessee middle Name in English
EnglishLastName Alpha(150) Bader Elm Lessee last Name in English

IHC– Auto Lease Integration Guide – Confidential Page | 17

 LesseeNationalityID Numeric(3) 104 (if LesseeID = Elm The nationality of the vehicle owner (Lessee).
Smallint 2XXXXXXXXX) Refer to LesseeNationality master table for supported
then YES values. (ELM CODE)
Else
(if LesseeID =
1XXXXXXXXX)
then 0
Else
null
VehicleUsagePercentage Numeric(3) 50 YES User This Lessee percentage of vehicle usage
Smallint input
LesseeOccupation Alphanumeric (25) ‫طبيب‬ YES Elm Lessee Occupation (Profession).
Refer to Occupation master table for supported values.
LesseeEducation Alphanumeric (25) Bachelor YES User Lessee Education (Qualification). Refer to Education master
input table for supported values.
LesseeChildrenBelow16 Numeric(2) 3 YES User Lessee Children Below 16 count
input
LesseeWorkCompanyName Alphanumeric (50) IHC Company No User Company Name where Lessee works
input
LesseeWorkCityID Numeric(3) 4 No User In which city Lessee works.
Smallint input Refer to Cities master table for supported values.
CountriesValidDrivingLicense JSON Array No User Other Countries Valid Driving License. Refer to
input “CountriesValidDrivingLicense” for more details.
LesseeNoOfClaims Int 0 No IHC Number of Claims with Lessee liability in last 5 years
LesseeTrafficViolationsCode Alphanumeric (50) 1,3,4 No User Lessee traffic violations ID’s, as selected by customer
input Refer to TrafficViolations master table for supported
values.
LesseeHealthConditionsCode Alphanumeric (50) 4,5 No User Lessee Health Conditions per License, as per ELM lookups
input Refer to HealthConditions master table for supported
values.
LesseeDateOfBirthG Alphanumeric (10) 07-11-1997 (if “LesseeID” Elm Lessee Date of Birth in “Gregorian” format (dd-MM-yyyy).
starts with 2)
then
YES
else
null
LesseeDateOfBirthH Alphanumeric (10) 29-07-1419 (if “LesseeID” Elm Lessee Date of Birth in “Hijri” format(dd-MM-yyyy).
starts with 1)
then
YES
else

IHC– Auto Lease Integration Guide – Confidential Page | 18

 null
LesseeGender tinyint 1 YES Elm Lessee Gender
1 : Male
2 : Female
LesseeMaritalStatus tinyint 1 YES Elm Lessee Martial Status.
Refer to MaritalStatus master table for supported values.
LesseeLicenseType Numeric(2) 1 YES Elm Lessee License Type. Refer to Driving License Type master
Tinyint table for supported values.
LesseeLicenseOwnYears Numeric(2) 5 YES User Lessee License Owning Years
Tinyint input
LesseeNCDCode Alphanumeric(10) 1 YES Najm The eligibility of Lessee and insured vehicle for No-Claim-
Discount (NCD). This information is taken from Najm
Company and expected values are from Najm lookup
In case IHC received Error from Najm, IHC will return Error
codes. Refer to NCDFreeYearsErrorCode for expected error
codes.
LesseeNCDReference Alphanumeric(50) NCD15061756985 NO Najm Reference Number generated by Najm System.
Format:NCD{DDMMYY}[Sequence}
LesseeNoOfAccidents Int 1 NO User Number of Accidents with Lessee liability in last 5 years
input
NajmCaseDetails JSON Array No Najm Details of accident(s) where the Lessee where contributed.
This information is taken from Najm Company for the Lessee
only.Refer to JSON Array Fields for “NajmCaseDetails”
for further details.
LesseeNationalAddress JSON array YES Elm Lessee’s National Address. Refer to “NationalAddress”for
more details.
DriverDetails JSON Array NO Driver(s) Details for additional drivers only. Refer to JSON
Array Fields for “DriverDetails” for further details.
5.1.1.1 JSON Array Fields for “DriverDetails”
This array will be used for additional drivers only.

Parameter Type(Size) Sample Mandatory Data Description

SQL Type Value Source
DriverID Numeric(10) XXXX943082 YES User input The driver ID (National ID Number, Iqama ID Number, or
Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
DriverFullName Alpha(150) ‫خالد أحمد‬ YES User The driver Name
input/Elm
ArabicFirstName Alpha(150) ‫سالم‬ YES Elm Driver fist Name in Arabic

IHC– Auto Lease Integration Guide – Confidential Page | 19

 ArabicMiddleName Alpha(150) ‫سعود‬ (if English isn’t sent) Elm Driver middle Name in Arabic
ArabicLastName Alpha(150) ‫بدر‬ Elm Driver last Name in Arabic
EnglishFirstName Alpha(150) Salem YES Elm Driver fist Name in English
EnglishMiddleName Alpha(150) Saud (if Arabic isn’t sent Elm Driver middle Name in English
EnglishLastName Alpha(150) Bader and) Elm Driver last Name in English
DriverRelation Tinyint 1 No User input This Parameter is added to describe the relationship between
the policy holder and the driver(s). the possible values are :
1: Father
2: Mother
3: Husband
4: Wife
5: Sun
6: Daughter
7: Brother
8: Sister
9: Employee
10: Sponsored
DriverNationalityID Numeric(3) 104 (if DriverID = Elm The nationality of the vehicle owner (Driver).
Smallint 2XXXXXXXXX) then Refer to Nationality master table for supported values. (ELM
YES CODE)
Else
(if DriverID =
1XXXXXXXXX) then 0
Else
null
VehicleUsagePercentage Numeric(3) 50 YES User input This driver percentage of vehicle usage
Smallint
DriverOccupation Alphanumeric ‫طبيب‬ YES Elm Driver Occupation (Profession).
(25) Refer to Occupation master table for supported values.
DriverEducation Alphanumeric Bachelor YES User input Driver Education (Qualification). Refer to Education master
(25) table for supported values.
DriverChildrenBelow16 Numeric(2) 3 YES User input Driver Children Below 16 count

DriverWorkCompanyName Alphanumeric IHC Company No User input Company Name where driver works
(50)
DriverWorkCityID Numeric(3) 4 No User input In which city driver works.
Smallint Refer to Cities master table for supported values.
CountriesValidDrivingLicense JSON Array No User input Other Countries Valid Driving License. Refer to
“CountriesValidDrivingLicense” for more details.

IHC– Auto Lease Integration Guide – Confidential Page | 20

 DriverNoOfClaims Int 0 No IHC Number of Claims with driver liability in last 5 years

DriverTrafficViolationsCode Alphanumeric 1,3,4 No User input Driver traffic violations ID’s, as selected by customer
(50) Refer to TrafficViolations master table for supported values.
DriverHealthConditionsCode Alphanumeric 4,5 No User input Driver Health Conditions per License, as per ELM lookups
(50) Refer to HealthConditions master table for supported
values.
DriverDateOfBirthG Alphanumeric 07-11-1997 (if “DriverID” starts User input Driver Date of Birth in “Gregorian” format (dd-MM-yyyy).
(10) with 2) then
YES
else
null
DriverDateOfBirthH Alphanumeric 29-07-1419 (if “DriverID” starts User input Driver Date of Birth in “Hijri” format(dd-MM-yyyy).
(10) with 1) then
YES
else
null
DriverGender tinyint 1 YES Elm Driver Gender
1 : Male
2 : Female

DriverMaritalStatus tinyint 1 YES User Driver Martial Status.

input/Elm Refer to MaritalStatus master table for supported values.
DriverHomeAddressCity Alphanumeric Riyadh No User input Driver Home Address City
(50)
DriverHomeAddress Alphanumeric Ibn Sina, No User input Driver Home Address
(100) ALmassif
DriverLicenseType Numeric(2) 1 YES Elm Driver License Type. Refer to Driving License Type master
Tinyint table for supported values.
DriverLicenseOwnYears Numeric(2) 5 YES User input Driver License Owning Years
Tinyint
DriverNoOfAccidents Int 1 NO User input Number of Accidents with driver liability in last 5 years

5.1.1.2 JSON Array Fields for “NajmCaseDetails”

Parameter Type(Size) Sample Value Mandatory Description
SQL Type
CaseNumber Alphanumeric(20) XXXX1013174 YES Najm Case Number
AccidentDate Alphanumeric(20) 2017-01- YES Najm Accident date
15T13:57:13
Liability Alphanumeric(10) 100 YES Driver Accident Liability

IHC– Auto Lease Integration Guide – Confidential Page | 21

 DriverAge Alphanumeric(3) 28 NO Driver Age
CarModel Alphanumeric(100) Toyota NO Vehicle Car Model
CarType Alphanumeric(100) Camry NO Vehicle Car Make
DriverID Alphanumeric(10) XXXX943082 YES Driver ID
SequenceNumber Alphanumeric(12) XXXX12345678 NO Vehicle Sequence Number
OwnerID Alphanumeric(12) XXXX943082 NO Vehicle Owner ID
EstimatedAmount Alphanumeric(20) 100.00 NO Claim Estimated Amount
DamageParts Alphanumeric(500) Test NO Damage Parts
CauseOfAccident Alphanumeric(500) Test NO Cause of Accidents
5.1.1.3 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four
5.1.1.4 JSON Array Fields for “NationalAddress”
Parameter Type (Size) Sample Value Mandatory Description
SQL Type
BuildingNumber Numeric(4) 1234 YES building NO in address.

Street Alphanumeric(200) King Abdullaziz road NO Street name

District Alphanumeric(100) Gadeer NO District name
City Alphanumeric(50) Riyadh YES City Name
ZipCode Numeric(5) 12345 YES Zip Code

AdditionalNumber Numeric(4) 1234 YES Additional Number of the address.

5.1.1.5 JSON Array Fields for “CountriesValidDrivingLicense”:
Parameter Type (Size) Sample Value Mandatory Description
SQL Type
DrivingLicenseCountryID Numeric(3) 104 Yes The country code where the driving license issued
Smallint As per ELM Countries lookup. Refer to
DrivingLicenseCountry master table for supported
values.
DriverLicenseYears Numeric(2) 5 YES Number of years driver had the driver license

IHC– Auto Lease Integration Guide – Confidential Page | 22

 Tinyint

Response Parameters For “Quote” Method:

Parameter Type(Size) Sample Mandatory Data Description Validations
SQL Type Value Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been ▪ It should match with already sent
sent to IC by IHC system. “RequestReferenceNo” in IHC DB.

InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by ▪ It should match with already exist
IHC. This code is Not changeable. Each “InsuranceCompanyCode” in IHC
insurance company will have its own DB
and fixed Code.
DriverDetails JSON Array NO IC Driver(s) Details for additional drivers ▪ It should be the same as
only. Refer to JSON Array Fields for “DriverDetails” IHC sent
“DriverDetails” for further details. ▪ It should match the DataType

LesseeID Numeric(10) XXXX943082 YES User The Lessee ID (National ID Number, ▪ It should be the same as
input Iqama ID Number, or Computer “LesseeID” IHC sent
Company ID). ▪ It should match the DataType
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
VehicleUsagePercentage Numeric(3) 50 YES User The Lessee percentage of vehicle usage ▪ It should be the same as
Smallint input “VehicleUsagePercentage” IHC
sent
LesseeDateOfBirthG Alphanumeric 07-11-1997 (if User Lessee Date of Birth in “Gregorian” ▪ It should be the same as
(10) “LesseeID” input format (dd-MM-yyyy). “DriverDateOfBirthG” IHC sent
starts with 2 It should match the DataType and
then) the format (dd-MM-yyyy).
YES
else
null
LesseeDateOfBirthH Alphanumeric 29-07-1419 (if User Lessee Date of Birth in “Hijri” ▪ It should be the same as
(10) “LesseeID” input format(dd-MM-yyyy). “DriverDateOfBirthH” IHC sent, It
starts with 1 should match the DataType and
then) the format (dd-MM-yyyy).
YES
else
null

IHC– Auto Lease Integration Guide – Confidential Page | 23

 LesseeGender tinyint 1 YES Elm Lessee Gender ▪ It should be the same as
1 : Male “DriverGender” IHC sent
2 : Female
NCDEligibility Tinyint 1 YES Najm What is the NCD Eligibility that IC
decided to give for this customer (0, 1,
2,3,4,5)
NajmCaseDetails JSON Array No Najm Details of accident(s) where the Lessee
where contributed. This information is
taken from Najm Company for the
Lessee only. Refer to JSON Array
Fields for “NajmCaseDetails” for
further details.
CompQuotes JSON Array YES IC Each compQuote array represents a ▪ None
different product/package.
Status Boolean True YES IC True: Success, ▪ It should match the DataType
False: Failure
errors JSON Array NO IC Refer Error Response Fields for more ▪ It should match the DataType
detail
5.1.1.6 JSON Array Fields for “CompQuotes”
Parameter Type(Size) Sample Mandatory Data Description Validations
SQL Type Value Source
QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance ▪ Must be uniquely
company system for each policy quote request generated by Insurance
Company. It should be
quote reference
number from IC
system.
PolicyTitleID Smallint 1 YES IC In case IC have multiple products for motor ▪ It should be the same
comprehensive, this field will determine which product as “PolicyTitleID” IHC
IHC is requesting for. sent.
Deductibles JSON Array YES IC This indicates all available deductibles that comes with ▪ None
the policy which ultimately affect the policy premium
price. Refer to “JSON Array Fields for “Deductibles” for
further details.
PolicyPremiumFeatures JSON Array YES IC Policy features including premium, regulated and free ▪ None
features. These features will appear to the customers and
it will make a difference for them to select the policy.
Refer to JSON Array Fields for “PremiumFeatures /
DynamicPremiumFeatures”: with a price for further
details.

IHC– Auto Lease Integration Guide – Confidential Page | 24

 CustomizedParameter JSON Array NO IC Custom parameters array in case of additional ▪ None
parameters required. Refer to “CustomizedParameter”
for further details.
5.1.1.7 JSON Array Fields for “DriverDetails”
Parameter Type(Size) Sample Value Mandatory Validations
SQL Type
DriverID Numeric(10) 1XXX943082 YES ▪ It should be the same as “DriverID” IHC sent

DriverName Alpha(150) ‫خالد أحمد‬ YES ▪ It should be the same as “DriverName” IHC sent
VehicleUsagePercentage Numeric(3) 50 YES ▪ It should be the same as “VehicleUsagePercentage” IHC
Smallint sent
DriverDateOfBirthG Alphanumeric (10) 07-11-1997 (if “DriverID” starts with 2 then) ▪ It should be the same as “DriverDateOfBirthG” IHC sent
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverDateOfBirthH Alphanumeric (10) 29-07-1419 (if “DriverID” starts with 1 then) ▪ It should be the same as “DriverDateOfBirthH” IHC sent,
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverGender tinyint 1 YES ▪ It should be the same as “DriverGender” IHC sent

NCDEligibility Tinyint 1 YES What was the NCD Eligibility that IC decided to give for
this customer (0, 1, 2,3,4,5)
5.1.1.8 JSON Array Fields for “Deductibles”:
Parameter Type(Size) Sample Mandatory Description Validations
SQL Type Value
DeductibleAmount Numeric(5) 500 YES The deductible amount in SAR ▪ None

PolicyPremium Numeric(8,2) 4500 YES The net price of the policy based on the deductible ▪ None
float amount in SAR
TaxableAmount Numeric(8,2) 4500 YES The total amount in SAR without VAT ▪ It should be equal
float or less than
PolicyPremium
BasePremium Numeric(8,2) 4500 YES The base premium of the policy based on the ▪ None
float deductible amount in SAR which will be collected
from the customer
PremiumBreakdown JSON Array Yes Json array of premium components to disclose ▪ Total value cannot
admin fees and other loadings that make up the be >
premium. Refer to “JSON Array Fields for PolicyPremium
“PremiunBreakdown”” for further details.

IHC– Auto Lease Integration Guide – Confidential Page | 25

 DynamicPremiumFeatures JSON Array NO Dynamic policy features including paid, and free ▪ None
(This Parameter will be features. These features will appear to the
used only if the IC offer customers based on the deductible and it will make
feature with prices vary a difference for them to select the policy. Refer to
based on the deductible) JSON Array Fields for “PremiumFeatures /
DynamicPremiumFeatures”: with a price for
further details.
Discounts* JSON Array NO This indicates all discounts that have been applied ▪ None
on the policy and their percentage. E.g., NCD,
Loyalty, etc.”.
Refer to “JSON Array Fields for “Discounts” for
further details
DeductibleReferenceNo* Alphanumeric(20) NO Unique reference number generated by Insurance ▪ None
company system could be used for each deductible.

5.1.1.9 JSON Array Fields for “PremiumFeatures / DynamicPremiumFeatures”:

Parameter Type (Size) Sample Value Mandatory Validations
SQL Type
FeatureID* SmallInt 7 YES This indicates the ID of the policy feature based on the
Policy Features master table. Refer to PolicyFeatures
lookup table.
Any feature ID shall only be shared in either
PolicyPremiumFeatures or DynamicPremiumFeatures. It
should not be repeated in both.
FeatureTypeID SmallInt 3 YES This indicate the feature type:
1 : Priced
2 : Free
3 : Regulated
FeatureAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Feature price if it’s premium feature
float YES
else
null
FeatureTaxableAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Taxable amount of the feature premium
float YES
else
null
5.1.1.10 JSON Array Fields for “Discounts”:
Parameter Type(Size) Sample Mandatory Description Validations
SQL Type Value

IHC– Auto Lease Integration Guide – Confidential Page | 26

 DiscountTypeID SmallInt 1 YES The discount type Refer to Discounts lookup table ▪ Should Match
ID’s in
Discounts
lookup table
DiscountPercentage Numeric(2,2) 10 YES Percentage of the discount as a part of 100, (e.g 10) ▪ 1 - 99
float
DiscountAmount Numeric(6,2) 400 YES The discount amount from the policy price, in SAR
float
5.1.1.11 JSON Array Fields for “PremiumBreakdown”:
Parameter Type (Size) Sample Mandatory Description Validations
SQL Type Value
BreakdownTypeID SmallInt 1 YES The breakdown type Refer to BreakdownMaster ▪ Should Match ID’s in
lookup table BreakdownMaster
lookup table
BreakdownAmount Numeric(6,2) 10 YES Amount of the breakdown item in SAR (e.g 25 ▪ 0 -> policypremim
float SAR)
BreakdownPercentage Numeric(2,2) 3 No Percentage upon which the breakdown was
float calculated (for loadings) if any.
5.1.1.12 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 27

5.2 “Policy” Method
IHC will post a request to IC web API to this method to get draft policy from IC. IC will validate the request and provide response (draft policy) to
IHC. The IC upon receiving this request will either keep the quote active with the respective deductible, premium and features selected by the
Lessor employee or disregard the request in other words, wait for the issuance request(next section) given that the quote must be active. The
main purpose of this method is to notify the IC to keep the quote active. If IC guarantees that the quote will remain active till policy issuance, IC
will not need this method.

See the Sequence diagram for “Policy” method on Figure 2.

Sequence Diagram:

Figure 2: Sequence diagram for "Policy" Method

IHC– Auto Lease Integration Guide – Confidential Page | 28

 Request Parameters for “Policy” Method:
Parameter Type(Size) Sample Value Mandatory Data Source Description
SQL Type
PolicyRequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each request from IHC system to IC API will
have Unique Policy Reference number
generated by IHC system.
InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by IHC.
Smallint This code is Not changeable. Each insurance
company will have its own and fixed Code.
RequestReferenceNo Alphanumeric(13) 323132 YES IHC Quote Request reference number generated
by IHC.
QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by
Insurance company system for each policy
quote request
Must be same as received from insurance
companies
Details
DeductibleReferenceNo Alphanumeric(20) NO IC Unique reference number generated by
Insurance company system could be used for
each deductible.
DeductibleAmount Numeric(5) 500 YES IC The deductible amount selected by customer
in SAR
PolicyPremiumFeatures JSON Array YES IC Policy features including premium, regulated
and free features. These features will appear
to the customers and it will make a difference
for them to select the policy. Refer to
“PremiumFeatures ” with a price for further
details.
DynamicPremiumFeatures JSON Array NO IC Dynamic policy features including premium,
and free features. These features will appear
to the customers based on the deductible and
it will make a difference for them to select the
policy. Refer to ““PremiumFeatures ” with a
price for further details.
CustomizedParameter JSON Array NO Custom parameters array in case of additional
parameters required. Refer to
“CustomizedParameter” for further details.

IHC– Auto Lease Integration Guide – Confidential Page | 29

5.2.1.1 JSON Array Fields for “PremiumFeatures / DynamicPremiumFeatures”:
Parameter Type (Size) Sample Value Mandatory Validations
SQL Type
FeatureID* SmallInt 7 YES This indicates the ID of the policy feature based on the
Policy Features master table. Refer to PolicyFeatures
lookup table.
Any feature ID shall only be shared in either
PolicyPremiumFeatures or DynamicPremiumFeatures. It
should not be repeated in both.
FeatureTypeID SmallInt 3 YES This indicate the feature type:
1 : Priced
2 : Free
3 : Regulated
FeatureAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Feature price if it’s premium feature
float YES
else
null
FeatureTaxableAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Taxable amount of the feature premium
float YES
else
null
5.2.1.2 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for “Policy” Method:

With successful response to IHC “Policy” request, insurance company will response back to that request with below parameters.

Parameter Type(Size) Sample Value Mandatory Data Source Description

SQL Type
Status Boolean True YES IC True: Success, ▪ It should match the
False: Failure DataType

IHC– Auto Lease Integration Guide – Confidential Page | 30

 errors JSON Array NO IC Refer Error Response ▪ It should match the
Fields for more detail DataType

5.3 “PolicyIssue” Method

IHC will post a request to IC web API to this method to issue a policy from IC. IC will validate the request and provide response (success or failure)
to IHC. See the Sequence diagram for “PolicyIssue” method on Figure 3.

IHC uses this method to Notify IC with a confirmation of policy issuance status (Success issuance).

Note: There might be failure while posting PolicyIssue to IC API; hence IHC ensures that they are maintaining failures of sending; therefore, IHC
will call IC at different intervals to make sure PolicyIssue has been passed to IC.

Sequence Diagram

Figure 3: Sequence diagram for "PolicyIssue" Method

IHC– Auto Lease Integration Guide – Confidential Page | 31

 Request Parameters for “PolicyIssue” Method:
Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
PolicyRequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each request from IHC system to IC API will have
Unique Policy Reference number generated by
IHC system.
InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by IHC. This
Smallint code is Not changeable. Each insurance company
will have its own and fixed Code.
RequestReferenceNo Alphanumeric(13) 323132 YES IHC Quote Request reference number generated by
IHC.
QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by
Insurance company system for each policy quote
request
Details
Email Alphanumeric(256) [email protected] YES User Lessee's (vehicle owner) email.
input
MobileNo Alphanumeric(10) 5XXX45678 YES User Lessee's (vehicle owner) mobile Number
input
LesseeID Numeric(10) XXXX943082 YES IHC The Lessee ID (National ID Number, Iqama ID
Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
PolicyEffectiveDate Alphanumeric(10) 2017-08-07 YES User The Date where the Policy is going to officially
input start/effective as per customer request (yyyy-
mm-dd).
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- NO IHC Policy number generated by IHC based on
1128 Insurance Company format.
DeductibleReferenceNo Alphanumeric(20) NO IHC Unique reference number generated by
Insurance company system could be used for
each deductible.
DeductibleAmount Numeric(5) 500 YES IHC The deductible amount selected by customer in
SAR
PaidAmount Numeric(8,2) float 4500 YES IHC The paid amount
BasePremium Numeric(8,2) 4500 YES IHC The base premium of the policy based on the
float deductible amount in SAR which will be collected
from the customer

IHC– Auto Lease Integration Guide – Confidential Page | 32

 PolicyPremiumFeatures JSON Array YES IHC Included Policy additional features selected by
the user. Refer to “PremiumFeatures” with a
price for further details.
DynamicPremiumFeatures JSON Array NO IHC Dynamic policy features including premium, and
free features. These features will appear to the
customers based on the deductible and it will
make a difference for them to select the policy.
Refer to PremiumFeatures” with a price for
further details.
VehicleUniqueTypeID Numeric(1) 1 YES IHC Unique ID to identify what is the Vehicle
tinyint identifier is used to get a policy;
1: By Sequence Number
2: By Custom Card.
VehicleSequenceNumber Numeric(12) XXXX12345678 (if User Vehicle Sequence Number which is written in the
”VehicleUniqueIDType” input registration Card (Istemarh) of vehicle
= 1)
YES
else
null
VehicleCustomID Numeric(12) XXXX12345678 (if User Vehicle custom Card in case the vehicle imported
”VehicleUniqueIDType”= input or still Not having a Registration Card (Istemarh)
2)
YES
else
null
VehiclePlateTypeID Numeric(2) 1 (if Elm Vehicle registration (plate) type code ID.
Tinyint “VehicleUniqueTypeID” Refer to VehiclePlateType master table for
= 1) supported values.
YES
else
null
VehiclePlateNumber Numeric(4) 9339 (if Elm Vehicle Plate Number format. In case of
Smallint “VehicleUniqueTypeID” Motorcycle, it will be two letters only.
= 1) Examples:
YES 3353 K R 2020 ‫ساد‬
else B
null Vehicle Plate 3353 2020
Number
First Plate Letter K ‫د‬
Second Plate R ‫ا‬
Letter

IHC– Auto Lease Integration Guide – Confidential Page | 33

 Third Plate Letter B ‫س‬

FirstPlateLetterID* Numeric(2) 2 (if Elm First plate Letter.

tinyint “VehicleUniqueTypeID” Refer to PlateCharacter master table for
= 1) supported values.
YES
else
null
SecondPlateLetterID* Numeric(2) 14 (if Elm Second plate Letter.
Tinyint “VehicleUniqueTypeID” Refer to PlateCharacter master table for
= 1) supported values.
YES
else
null
ThirdPlateLetterID* Numeric(2) 10 (if Elm Third plate Letter.
Tinyint (“VehicleUniqueIDType” Refer to PlateCharacter master table for
= 1) and supported values.
(“VehiclePlateTypeID”
<> ‘10’))
YES
else
null
VehicleVIN Alphanumeric (17) 1FAHP2D86FG204916 YES Elm Vehicle identification number, commonly
abbreviated to VIN, or chassis number
VehicleRegistrationExpiryDate Alphanumeric(10) 29-07-1438 (if Elm Vehicle Registration (Istemarah) expiry date in
“VehicleUniqueTypeID” Hijri.
= 1)
YES
else
null
VehicleWeight Numeric(5) 1696 NO Elm Lessee's (vehicle owner) vehicle weight

IHC– Auto Lease Integration Guide – Confidential Page | 34

 VehicleBodyCode Numeric(3) 5 NO Elm Lessee's (vehicle owner) body code of the vehicle
SmallInt (ELM Code) Refer to Vehicle Body master table
for supported values.
CustomizedParameter JSON Array NO IHC Custom parameters array in case of additional
parameters required. Refer to
“CustomizedParameter” for further details.
5.3.1.1 JSON Array Fields for “PremiumFeatures / DynamicPremiumFeatures”:
Parameter Type (Size) Sample Value Mandatory Validations
SQL Type
FeatureID* SmallInt 7 YES This indicates the ID of the policy feature based on the
Policy Features master table. Refer to PolicyFeatures
lookup table.
Any feature ID shall only be shared in either
PolicyPremiumFeatures or DynamicPremiumFeatures. It
should not be repeated in both.
FeatureTypeID SmallInt 3 YES This indicate the feature type:
1 : Priced
2 : Free
3 : Regulated
FeatureAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Feature price if it’s premium feature
float YES
else
null
FeatureTaxableAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Taxable amount of the feature premium
float YES
else
null
5.3.1.2 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 35

 Response Parameters for “PolicyIssue” Method
Parameter Type(Size) Sample Value Mandatory Data Description Validations
SQL Type Source
PolicyReferenceNo Numeric(10) 4654654 YES IC Response Reference No generated by ▪ None
IC API at the time of providing policy,
to identify the policy in IHC
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- NO IC Policy Number Generated by IC ▪ None
1128 system.
PolicyEffectiveDate Alphanumeric(10) 2017-08-07 YES IC The Date where the Policy is going to ▪ It should match the DataType
officially start/effective as per (> current Date)
customer request (yyyy-mm-dd).
PolicyExpiryDate Alphanumeric(10) 2018-08-06 YES IC When the Policy is going to be ((PolicyExpiryDate–
Expired PolicyEffectiveDate) = 365 days (or
plus or minus 3 days))
Status Boolean True YES IC True: Success, It should match the DataType
False: Failure
errors JSON Array IC Refer Error Response Fields for more
detail

IHC– Auto Lease Integration Guide – Confidential Page | 36

5.4 “UpdatePolicyNumber” Method
IC uses this method to once they receive a PolicyIssue from IHC and wish to update the IHC policy details with the correct policy number that was
uploaded to NAJM. See the Sequence diagram for “UpdatePolicyNumber” method on Figure 4.

Suggestion: There might be failure while posting updated policy number to IHC API; hence IC has to make sure that they are maintaining failures
of sending; therefore, IC can call IHC at different interval to make sure policy number has been passed to IHC.

Sequence Diagram

Figure 4: Sequence diagram for "UpdatePolicyNumber" Method

IHC– Auto Lease Integration Guide – Confidential Page | 37

 Request Parameters for UpdatePolicyNumber:
Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
PolicyRequestReferenceNo Alphanumeric(13) 7442232 YES IHC Unique Policy Reference number generated by IHC system for
policy request.
InsuranceCompanyCode Numeric(3) 123 YES IC Insurance company Code provided by IHC. This code is Not
Smallint changeable. Each insurance company will have its own and fixed
Code.
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference NO generated by IC API at the time of
providing policy, to identify the policy in IHC
OldPolicyNumber Alphanumeric(100) 13/60/XXX/2000- NO IC Old Policy number generated by Insurance Company system at
1100 policy issuance stage
NewPolicyNumber Alphanumeric(100) 13/60/XXX/2000- Yes IC New Policy number generated by Insurance Company system
1128 after purchase notification
LessorID Numeric(10) 7005454545 YES IC Company enterprise 700 Number (7XXXXXXXXX) as Ministry of
Commerce
LesseeID Numeric(10) XXXX943082 YES IC Lessee (Vehicle Owner) ID (National ID Number, Iqama ID
Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
CustomizedParameter JSON Array NO IC Custom parameters array in case of additional parameters
required. Refer to “CustomizedParameter” for further details.
5.4.1.1 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 38

 Response Parameters for UpdatePolicyNumber:
Parameter Type(Size) Data Source Sample Value Mandatory Description
SQL Type
Status Boolean IHC True YES True: Processed
False: Not Processed
errors JSON Array IHC NO Refer Error Response Fields for more
detail

IHC– Auto Lease Integration Guide – Confidential Page | 39

5.5 “VehicleIDUpdate” Method
IC uses this method to send Najm VehicleID number to IHC after successful upload the policy to National Information Center (NIC) via Najm (this is
only for purchased policies). See the Sequence diagram for “VehicleIDUpdate” method on Figure 5.

Suggestion: There might be failure while posting VehicleID to IHC API; hence IC has to make sure that they are maintaining failures of sending;
therefore, IC can call IHC at different intervals to make sure VehicleID has been passed to IHC.

Sequence Diagram

Figure 5. Sequence diagram for "VehicleIDUpdate" Method

Request Parameters for VehicleIDUpdate:

Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
PolicyRequestReferenceNo Alphanumeric(13) 323213132 YES IHC Unique Policy Reference number generated by IHC
system for policy request.
InsuranceCompanyCode Numeric(3) 123 YES IC Insurance company Code provided by IHC. This
Smallint code is Not changeable. Each insurance company
will have its own and fixed Code.

IHC– Auto Lease Integration Guide – Confidential Page | 40

 PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API
at the time of providing policy quote
LessorID Numeric(10) 7005454545 YES IC Company enterprise 700 Number (7XXXXXXXXX) as
Ministry of Commerce
LesseeID Numeric(10) XXXX943082 YES IC Lessee (Vehicle Owner) ID (National ID Number,
Iqama ID Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
VehicleSequenceNumber Numeric(12) XXXX12345678 No IC Vehicle Sequence Number which is written in the
registration Card (Istemarh) of vehicle
VehicleCustomID Numeric(12) XXXX12345678 No IC Vehicle custom Card in case the vehicle imported
or still Not having a Registration Card (Istemarh)
NajmVehicleId Numeric(18) If rejected, then -1 else YES IC Unique ID generated from Najm during policy
for ex. 876868768 registration by IC.
RejectionReason Alphanumeric(100) This Vehicle has 2 Active If NajmVehicleId = -1, IC Reason policy got rejected as received from Najm.
Insurances For The Same then yes. Otherwise
Owner No.
PolicyUploadedDateTime Alphanumeric(20) 2017-08-05 15:30:33 YES IC The Date & Time where IC has uploaded purchased
policy and received success response from Najm
system (yyyy-MM-dd HH:mm:ss)
CustomizedParameter JSON Array NO IC Custom parameters array in case of additional
parameters required. Refer to
“CustomizedParameter” for further details.
5.5.1.1 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for VehicleIDUpdate:

Parameter Type(Size) Sample Value Mandatory Data Source Description
SQL Type

IHC– Auto Lease Integration Guide – Confidential Page | 41

 Status Boolean True YES IHC True: Processed
False: Not Processed
Errors JSON Array NO IHC Refer Error Response Fields for
more detail

IHC– Auto Lease Integration Guide – Confidential Page | 42

5.6 “IcUpdatePolicy” Method
This method will be hosted at IC end, and IHC will call it to update the policy information at IC side.
The client will be able to update the policy information through IHC if this change will not affect the price.
IHC will do all the required verification for the information provided by the client before requesting the method.
See the Sequence diagram for “IcUpdatePolicy” method on Figure 6.

Sequence Diagram:

Figure 6:. Sequence diagram for "IcUpdatePolicy" Method

IHC– Auto Lease Integration Guide – Confidential Page | 43

 Request Parameters for “IcUpdatePolicy” Method:
Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
RequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each Quote request from IHC system to
IC API will have Unique Request
Reference number generated by IHC
system.
QuoteReferenceNo Numeric(15) 1000255 YES IC Unique reference number generated by
Insurance company system for each
quote request
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- YES IC or IHC Policy number generated by Insurance
1128 Company system or IHC
LessorID Numeric(10) 7005454545 YES IHC Company enterprise 700 Number
(7XXXXXXXXX) as Ministry of Commerce
LesseeID Numeric(10) XXXX943082 YES IHC Lessee (Vehicle Owner) ID (National ID
Number, Iqama ID Number, or Computer
Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
VehicleSequenceNumber Numeric(12) XXXX12345678 YES Elm Vehicle Sequence Number which is
written in the registration Card
(Istemarh) of vehicle
VehicleCustomID Numeric(12) XXXX12345678 (if ”UpdatePolicyReasonID”= 2) IHC Vehicle custom Card in case the vehicle
YES imported or still Not having a Registration
else Card (Istemarh)
null
VehiclePlateTypeID Numeric(2) 1 (if “UpdatePolicyReasonID” = 2 or 3 Elm Vehicle registration (plate) type code ID.
Tinyint and “VehicleSequenceNumber”<> Refer to VehiclePlateType master table
null) for supported values.
YES
else
null
VehiclePlateNumber Numeric(4) 9339 (if “UpdatePolicyReasonID” = 2 or 3) Elm Vehicle Plate Number format. In case of
Smallint YES Motorcycle, it will be two letters only.
else Examples:
null 3353 K 2020 ‫ساد‬
RB
Vehicle Plate 3353 2020
Number
First Plate K ‫د‬
Letter

IHC– Auto Lease Integration Guide – Confidential Page | 44

 Second Plate R ‫ا‬
Letter
Third Plate B ‫س‬
Letter

FirstPlateLetterID* Numeric(2) 2 (if “UpdatePolicyReasonID” = 2 or 3) Elm First plate Letter.

tinyint YES Refer to PlateCharacter master table for
else supported values.
null
SecondPlateLetterID* Numeric(2) 14 (if “UpdatePolicyReasonID” = 2 or 3) Elm Second plate Letter.
Tinyint YES Refer to PlateCharacter master table for
else supported values.
null

ThirdPlateLetterID* Numeric(2) 10 ((if “UpdatePolicyReasonID” = 2 or 3) Elm Third plate Letter.

Tinyint & VehiclePlateTypeID <> 10) Refer to PlateCharacter master table for
YES supported values.
else
null
Email Alphanumeric(256) [email protected] (if “UpdatePolicyReasonID” = 1) User Lessee's (vehicle owner) email.
YES input
else
null
MobileNo Alphanumeric(10) 5XXX45678 (if “UpdatePolicyReasonID” = 1) User Lessee's (vehicle owner) mobile Number
YES input
else
null
NationalAddress JSON Array (if “UpdatePolicyReasonID” = 4) Elm Lessee's (vehicle owner) National
YES address.
else Refer to JSON Array Fields for
null “NationalAddress” for more details.
UpdatePolicyReasonID Numeric(1) 1 YES IHC The reason the policy needs to get
tinyint updated. Refer to UpdateReason master
table for supported values.

IHC– Auto Lease Integration Guide – Confidential Page | 45

5.6.1.1 JSON Array Fields for “NationalAddress”
Parameter Type (Size) Sample Value Mandatory Description
SQL Type
BuildingNumber Numeric(4) 1234 YES building NO in address.

Street Alphanumeric(200) King Abdullaziz road NO Street name

District Alphanumeric(100) Gadeer NO District name
City Alphanumeric(50) Riyadh YES City Name
ZipCode Numeric(5) 12345 YES Zip Code

AdditionalNumber Numeric(4) 1234 YES Additional Number of the address.

Response Parameters for “IcUpdatePolicy” Method:

Parameter Type(Size) Sample Value Mandatory Data Source Description Validations
SQL Type
Status Boolean True YES IC True: Success, ▪ It should match the DataType
False: Failure
errors JSON Array NO IC Refer Error Response Fields for more detail ▪ It should match the DataType

IHC– Auto Lease Integration Guide – Confidential Page | 46

5.7 “AddFeature” Method
The method will be hosted at IC’s end, so that IHC can call it to update the policy details.
This function will allow the addition of multiple features/covers to a purchased a policy. By 1st inquiring about the available features at IC side
using ‘QueryFeature’ then confirming the selected features using ‘PurchaseFeature’.
See the Sequence diagram for “AddFeature” method on Figure 7.

Note: This functionality will be used to add additional features only, free features will not be allowed.

Sequence Diagram

Figure 7: Sequence diagram for "AddFeature" Method

IHC– Auto Lease Integration Guide – Confidential Page | 47

 Request Parameters for “QueryFeature” Method:
Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been sent to IC by IHC system.

QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance company
system for each policy request
Must be same as received from insurance companies
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API at the time
of providing policy quote
QueryRequestReferenceNo Numeric(10) 4654654 YES IHC Query Feature Request generated by IHC API at the time of
querying for features
InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by IHC. This code is Not
Smallint changeable. Each insurance company will have its own and fixed
Code.
LesseeID Numeric(10) XXXX943082 YES Client Lessee (Vehicle Owner) ID (National ID Number, Iqama ID
Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
LessorID Numeric(10) 7005454545 YES IHC Company enterprise 700 Number (7XXXXXXXXX) as Ministry of
Commerce
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- YES IC or Policy number generated by Insurance Company system or IHC
1128 IHC
VehicleSequenceNumber Numeric(12) XXXX12345678 No Client Vehicle Sequence Number which is written in the registration
Card (Istemarh) of vehicle
VehicleCustomID Numeric(12) XXXX12345678 No Client Vehicle custom Card in case the vehicle imported or still Not
having a Registration Card (Istemarh)

VehicleVIN Alphanumeric (17) 1FAHP2D86FG204916 NO Elm Vehicle identification number, commonly abbreviated to VIN, or
chassis number
CustomizedParameter JSON Array NO Custom parameters array in case of additional parameters
required. Refer to “CustomizedParameter” for further
details.
5.7.1.1 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One

IHC– Auto Lease Integration Guide – Confidential Page | 48

 Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for “QueryFeature” Method:

Parameter Type(Size) Sample Mandatory Data Description Validations
SQL Type Value Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been sent ▪ It should be the same as
to IC by IHC system. “RequestReferenceNo” IHC
sent.
QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by ▪ It should be the same as
Insurance company system for each “QuoteReferenceNo” IHC sent.
policy request
Must be same as received from
insurance companies
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No ▪ It should be the same as
generated by IC API at the time of “PolicyReferenceNo” IHC sent.
providing policy quote
QueryRequestReferenceNo Numeric(10) 4654654 YES IHC Query Feature Request generated by ▪ It should be the same as
IHC API at the time of querying for “QueryRequestReferenceNo”
features IHC sent.
QueryResponseReferenceNo Numeric(10) 4654654 YES IC Query Feature Response generated by IC
API at the time of querying for features
InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Codeprovided by ▪ It should be the same as
Smallint IHC. This code is Not changeable. Each “InsuranceCompanyCode” IHC
insurance company will have its own and sent.
fixed Code.
PolicyPremiumFeatures JSON Array YES Policy features including premium,
regulated and free features. These
features will appear to the customers
and it will make a difference for them to
select the policy. Refer to JSON Array
Fields for “PremiumFeatures” with a
price for further details.
Status Boolean True YES IC True: Success, It should match the DataType
False: Failure
errors JSON Array NO IC Refer Error Response Fields for more
detail

IHC– Auto Lease Integration Guide – Confidential Page | 49

 CustomizedParameter JSON Array NO Custom parameters array in case of
additional parameters required. Refer to
“CustomizedParameter” for further
details.
5.7.1.2 JSON Array Fields for “PremiumFeatures”:
Parameter Type (Size) Sample Value Mandatory Validations
SQL Type
FeatureID SmallInt 7 YES This indicates the ID of the policy feature based on the
Policy Features master table. Refer to PolicyFeatures
lookup table.
Any feature ID shall only be shared in either
PolicyPremiumFeatures or DynamicPremiumFeatures. It
should not be repeated in both.
FeatureTypeID SmallInt 2 YES This indicate the feature type:
1 : Priced

FeatureAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Feature price if it’s premium feature
float YES
else
null
FeatureTaxableAmount Numeric(6,2) 4500 (if FeatureTypeID == 1) then Taxable amount of the feature premium
float YES
else
null
5.7.1.3 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 50

 Request Parameters for “PurchaseFeature” Method:
Parameter Type(Size) Sample Mandatory Data Description
SQL Type Value Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been sent to IC by IHC system.

QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance company system
for each policy request
Must be same as received from insurance companies
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API at the time of
providing policy quote
QueryRequestReferenceNo Numeric(10) 4654654 YES IHC Query Feature Request generated by IHC API at the time of
querying for features
QueryResponseReferenceNo Numeric(10) 4654654 YES IC Query Feature Response generated by IC API at the time of
querying for features
AdditionalPremium Numeric(8,2) 4500 YES IC Total amount of selected features to be charged.
float
AddedFeatures JSON Array YES
CustomizedParameter JSON Array NO Custom parameters array in case of additional parameters required.
Refer to “CustomizedParameter” for further details.

5.7.1.4 JSON Array Fields for “CustomizedParameter”

Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four
5.7.1.5 JSON Array Fields for “AddedFeatures”:
Parameter Type (Size) Sample Value Mandatory Data Source Validations
SQL Type
FeatureID SmallInt 7 YES IC This indicates the ID of the policy feature
based on the Policy Features master table.
Refer to PolicyFeatures lookup table
FeatureAmount Numeric(6,2) 4500 YES IC Feature price if it’s premium feature
float

IHC– Auto Lease Integration Guide – Confidential Page | 51

 FeatureTaxableAmount Numeric(6,2) 4500 YES IC Taxable amount of the feature premium
float

Response Parameters for “PurchaseFeature” Method:

Parameter Type(Size) Sample Value Mandatory Data Source Description Validations
SQL Type
Status Boolean True YES IHC True: Success, ▪ It should match the DataType
False: Failure
errors JSON Array NO IHC Refer Error Response Fields for more detail ▪ It should match the DataType

IHC– Auto Lease Integration Guide – Confidential Page | 52

5.8 “AddDriver” Method
The method will be hosted at IC’s end, so that IHC can call it to update the policy details.
This function will allow the addition of driver(s) to a purchased a policy. By 1st passing the driver details and inquiring about the additional charge
using ‘AddDriver’ then confirming the added drivers using ‘ConfirmAddDrivers.
The diagram shows the flow of the method. See the Sequence diagram for “AddDriver” method on Figure 8.

Sequence Diagram

Figure 8:Sequence diagram for "AddDriver" Method

Request Parameters for “AddDriver” Method:

Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been sent to IC by IHC system.

QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance company
system for each policy request
Must be same as received from insurance companies

IHC– Auto Lease Integration Guide – Confidential Page | 53

 PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API at the time
of providing policy quote
AddDriverRequestReferenceNo Numeric(10) 4654654 YES IHC Add Driver Request generated by IHC API

InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code provided by IHC. This code is Not
Smallint changeable. Each insurance company will have its own and fixed
Code.
LesseeID Numeric(10) XXXX943082 YES Client Lessee (Vehicle Owner) ID (National ID Number, Iqama ID
Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
LessorID Numeric(10) 7005454545 YES IHC Company enterprise 700 Number (7XXXXXXXXX) as Ministry of
Commerce
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- YES IC or IHC Policy number generated by Insurance Company system or IHC
1128
VehicleUsagePercentage Numeric(3) 50 YES User The Lessee percentage of vehicle usage
Smallint input
VehicleSequenceNumber Numeric(12) XXXX12345678 No Client Vehicle Sequence Number which is written in the registration
Card (Istemarh) of vehicle
VehicleCustomID Numeric(12) XXXX12345678 No Client Vehicle custom Card in case the vehicle imported or still Not
having a Registration Card (Istemarh)
DriverDetails JSON Array YES Driver(s) Details for additional drivers only. Refer to JSON
Array Fields for “DriverDetails” for further details.
CustomizedParameter JSON Array NO Custom parameters array in case of additional parameters
required. Refer to “CustomizedParameter” for further
details.
5.8.1.1 JSON Array Fields for “DriverDetails”
This array will be used for additional drivers only.

Parameter Type(Size) Sample Mandatory Data Description

SQL Type Value Source
DriverID Numeric(10) XXXX943082 YES User input The driver ID (National ID Number, Iqama ID Number, or
Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
DriverFullName Alpha(150) ‫خالد أحمد‬ YES User The driver Name
input/Elm
ArabicFirstName Alpha(150) ‫سالم‬ YES Elm Driver fist Name in Arabic
ArabicMiddleName Alpha(150) ‫سعود‬ (if English isn’t sent) Elm Driver middle Name in Arabic
ArabicLastName Alpha(150) ‫بدر‬ Elm Driver last Name in Arabic

IHC– Auto Lease Integration Guide – Confidential Page | 54

 EnglishFirstName Alpha(150) Salem YES Elm Driver fist Name in English
EnglishMiddleName Alpha(150) Saud (if Arabic isn’t sent Elm Driver middle Name in English
EnglishLastName Alpha(150) Bader and) Elm Driver last Name in English
DriverNationalityID Numeric(3) 104 (if DriverID = Elm The nationality of the vehicle owner (Driver).
Smallint 2XXXXXXXXX) then Refer to Nationality master table for supported values. (ELM
YES CODE)
Else
(if DriverID =
1XXXXXXXXX) then 0
Else
null
VehicleUsagePercentage Numeric(3) 50 YES User input This driver percentage of vehicle usage
Smallint
DriverRelation Tinyint 1 No User input This Parameter is added to describe the relationship between
the policy holder and the driver(s). the possible values are :
1: Father
2: Mother
3: Husband
4: Wife
5: Sun
6: Daughter
7: Brother
8: Sister
9: Employee
10: Sponsored
DriverOccupation Alphanumeric ‫طبيب‬ YES Elm Driver Occupation (Profession).
(25) Refer to Occupation master table for supported values.
DriverEducation Alphanumeric Bachelor YES User input Driver Education (Qualification). Refer to Education master
(25) table for supported values.
DriverChildrenBelow16 Numeric(2) 3 YES User input Driver Children Below 16 count

DriverWorkCompanyName Alphanumeric IHC Company No User input Company Name where driver works
(50)
DriverWorkCityID* Numeric(3) 4 No User input In which city driver works.
Smallint Refer to Cities master table for supported values.
CountriesValidDrivingLicense JSON Array No User input Other Countries Valid Driving License. Refer to
“CountriesValidDrivingLicense” for more details.
DriverNoOfClaims Int 0 No IHC Number of Claims with driver liability in last 5 years

DriverTrafficViolationsCode Alphanumeric 1,3,4 No User input Driver traffic violations ID’s, as selected by customer
(50)

IHC– Auto Lease Integration Guide – Confidential Page | 55

 Refer to TrafficViolations master table for supported values.

DriverHealthConditionsCode Alphanumeric 4,5 No User input Driver Health Conditions per License, as per ELM lookups
(50) Refer to HealthConditions master table for supported
values.
DriverDateOfBirthG Alphanumeric 07-11-1997 (if “DriverID” starts User input Driver Date of Birth in “Gregorian” format (dd-MM-yyyy).
(10) with 2) then
YES
else
null
DriverDateOfBirthH Alphanumeric 29-07-1419 (if “DriverID” starts User input Driver Date of Birth in “Hijri” format(dd-MM-yyyy).
(10) with 1) then
YES
else
null
DriverGender tinyint 1 YES Elm Driver Gender
1 : Male
2 : Female

DriverMaritalStatus tinyint 1 YES User Driver Martial Status.

input/Elm Refer to MaritalStatus master table for supported values.
DriverHomeAddressCity Alphanumeric Riyadh No User input Driver Home Address City
(50)
DriverHomeAddress Alphanumeric Ibn Sina, No User input Driver Home Address
(100) ALmassif
DriverLicenseType Numeric(2) 1 YES Elm Driver License Type. Refer to Driving License Type master
Tinyint table for supported values.
DriverLicenseOwnYears Numeric(2) 5 YES User input Driver License Owning Years
Tinyint
DriverNoOfAccidents Int 1 NO User input Number of Accidents with driver liability in last 5 years

5.8.1.2 JSON Array Fields for “CustomizedParameter”

Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 56

 Response Parameters for “AddDriver” Method:
Parameter Type(Size) Sample Mandatory Data Description Validations
SQL Type Value Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has It should be the same as
been sent to IC by IHC system. “RequestReferenceNo” IHC sent.

QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number It should be the same as
generated by Insurance “QuoteReferenceNo” IHC sent.
company system for each policy
request
Must be same as received from
insurance companies
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No ▪ It should be the same as
generated by IC API at the time “PolicyReferenceNo” IHC sent.
of providing policy quote
AddDriverRequestReferenceNo Numeric(10) 4654654 YES IHC Add Driver Request generated ▪ It should be the same as
by IHC API “AddDriverRequestReferenceNo”
IHC sent.
AddDriverResponseReferenceNo Numeric(10) 4654654 YES IC Add Driver Response generated
by IC API
InsuranceCompanyCode Numeric(3) 123 YES IHC Insurance company Code ▪ It should be the same as
Smallint provided by IHC. This code is Not “InsuranceCompanyCode” IHC
changeable. Each insurance sent.
company will have its own and
fixed Code.
DriversBreakdown JSON Array YES IC Refer to JSON Array Fields for
“DriversBreakdown” for more
details. This array should include
the additional drivers only
AdditionalPremium Numeric(8,2) 4500 YES IC The net price for the additional
float driver(s) SAR
Status Boolean True YES IC True: Success,
False: Failure
errors JSON Array NO IC Refer Error Response Fields for
more detail

IHC– Auto Lease Integration Guide – Confidential Page | 57

 CustomizedParameter JSON Array NO Custom parameters array in case
of additional parameters
required. Refer to
“CustomizedParameter” for
further details.
5.8.1.3 JSON Array Fields for “DriversBreakdown”
Parameter Type(Size) Sample Value Mandatory Validations
SQL Type
DriverID Numeric(10) 1XXX943082 YES ▪ It should be the same as “DriverID” IHC sent

DriverName Alpha(150) ‫خالد أحمد‬ YES ▪ It should be the same as “DriverName” IHC sent
VehicleUsagePercentage Numeric(3) 50 YES ▪ It should be the same as “VehicleUsagePercentage” IHC
Smallint sent
DriverDateOfBirthG Alphanumeric (10) 07-11-1997 (if “DriverID” starts with 2 then) ▪ It should be the same as “DriverDateOfBirthG” IHC sent
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverDateOfBirthH Alphanumeric (10) 29-07-1419 (if “DriverID” starts with 1 then) ▪ It should be the same as “DriverDateOfBirthH” IHC sent,
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverGender tinyint 1 YES ▪ It should be the same as “DriverGender” IHC sent

NCDEligibility Tinyint 1 YES What was the NCD Eligibility that IC decided to give for
this customer (0, 1, 2,3,4,5)
DriverAmount Numeric(6,2) 4500 YES Price for adding this driver, if any.
float

5.8.1.4 JSON Array Fields for “CustomizedParameter”

Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

IHC– Auto Lease Integration Guide – Confidential Page | 58

 Request Parameters for “ConfirmAddDriver” Method:
Parameter Type(Size) Sample Mandatory Data Description
SQL Type Value Source
RequestReferenceNo Alphanumeric(13) 3000255 YES IHC Request Reference ID that has been sent to IC by IHC system.

QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance company system
for each policy request
Must be same as received from insurance companies
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API at the time of
providing policy quote
AddDriverRequestReferenceNo Numeric(10) 4654654 YES IHC Add Driver Request generated by IHC API

AddDriverResponseReferenceNo Numeric(10) 4654654 YES IC Add Driver Response generated by IC API

DriversBreakdown JSON Array YES IC Refer to JSON Array Fields for “DriversBreakdown” for more details.
This array should include the additional drivers only
AdditionalPremium Numeric(8,2) 4500 YES IHC Total amount of drivers to be added.
float
CustomizedParameter JSON Array NO Custom parameters array in case of additional parameters required.
Refer to “CustomizedParameter” for further details.
5.8.1.5 JSON Array Fields for “DriversBreakdown”
Parameter Type(Size) Sample Value Mandatory Validations
SQL Type
DriverID Numeric(10) 1XXX943082 YES ▪ It should be the same as “DriverID” IHC sent

DriverName Alpha(150) ‫خالد أحمد‬ YES ▪ It should be the same as “DriverName” IHC sent
VehicleUsagePercentage Numeric(3) 50 YES ▪ It should be the same as “VehicleUsagePercentage” IHC
Smallint sent
DriverDateOfBirthG Alphanumeric (10) 07-11-1997 (if “DriverID” starts with 2 then) ▪ It should be the same as “DriverDateOfBirthG” IHC sent
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverDateOfBirthH Alphanumeric (10) 29-07-1419 (if “DriverID” starts with 1 then) ▪ It should be the same as “DriverDateOfBirthH” IHC sent,
YES It should match the DataType and the format (dd-MM-
else yyyy).
null
DriverGender tinyint 1 YES ▪ It should be the same as “DriverGender” IHC sent

IHC– Auto Lease Integration Guide – Confidential Page | 59

 NCDEligibility Tinyint 1 YES What was the NCD Eligibility that IC decided to give for
this customer (0, 1, 2,3,4,5)
DriverAmount Numeric(6,2) 4500 YES Price for adding this driver, if any.
float

5.8.1.6 JSON Array Fields for “CustomizedParameter”

Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for “ConfirmAddDriver” Method:

Parameter Type(Size) Sample Value Mandatory Data Source Description Validations
SQL Type
Status Boolean True YES IC True: Success, ▪ It should match the DataType
False: Failure
errors JSON Array NO IC Refer Error Response Fields for more detail ▪ It should match the DataType

IHC– Auto Lease Integration Guide – Confidential Page | 60

5.9 “CancelPolicy” Method
IC uses this method to notify IHC about the cancellation of a policy issued through IHC Portal. See the Sequence diagram for “CancelPolicy”
method on Figure 9.

Sequence Diagram

Figure 9: Sequence diagram for "CancelPolicy" Method

Request Parameters for “CancelPolicy” Method

Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
PolicyRequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each request from IHC system to IC API will have
Unique Policy Reference number generated by
IHC system.
InsuranceCompanyCode Numeric(3) 123 YES IC Insurance company Codeprovided by IHC. This
Smallint code is Not changeable. Each insurance company
will have its own and fixed Code.
RequestReferenceNo Alphanumeric(13) 323132 YES IHC Quote Request reference number generated by
IHC.

IHC– Auto Lease Integration Guide – Confidential Page | 61

 QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by
Insurance company system for each policy quote
request
PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC
API at the time of providing policy quote
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- YES IC or Policy number generated by Insurance Company
1128 IHC system or IHC
LessorID Numeric(10) 7005454545 YES IC Company enterprise 700 Number (7XXXXXXXXX)
as Ministry of Commerce
LesseeID Numeric(10) XXXX943082 YES IC Lessee (Vehicle Owner) ID (National ID Number,
Iqama ID Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
VehicleSequenceNumber Numeric(12) XXXX12345678 (if ”VehicleCustomID” = null) IC Vehicle Sequence Number which is written in the
then registration Card (Istemarh) of vehicle
YES
else
null
VehicleCustomID Numeric(12) XXXX12345678 (if ”VehicleSequenceNumber”= IC Vehicle custom Cardin case the vehicle imported
null) then or still Not having a Registration Card (Istemarh)
YES
else
null
IsCancelled Boolean True YES IC TRUE to cancel a policy, FALSE to undo a
previous mistaken cancellation

CancellationTime Alphanumeric(20) 2017-08-05 YES IC The Date & Time when policy get cancelled.
15:30:33 (yyyy-MM-dd HH:mm:ss)
CancellationReason Numeric(3) 12 YES IC Refer to CancellationReason master table for
Smallint supported values.
RequestedCommission Numeric(8,2) 23.32 YES IC The amount requested from IC based on the
Float refunded amount.
RefundedAmount Numeric(8,2) 1323.32 YES IC The amount that was refunded from IC to the
Float client.
CustomizedParameter JSON Array NO IC Custom parameters array in case of additional
parameters required. Refer to
“CustomizedParameter” for further details.

IHC– Auto Lease Integration Guide – Confidential Page | 62

5.9.1.1 JSON Array Fields for “CustomizedParameter”
Parameter Type(Size) Sample Value Mandatory Description
SQL Type
Key Alphanumeric (50) Age YES Custom Parameter Key Name
Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for “CancelPolicy” Method

Parameter Type(Size) Sample Value Mandatory Data source Description Validations
SQL Type
Status Boolean True YES IHC True: Success, It should match the DataType
False: Failure
errors JSON Array Refer Error Response Fields for more detail

IHC– Auto Lease Integration Guide – Confidential Page | 63

5.10 “IcCancelPolicy” Method
IHC uses this method to notify IC about the cancellation of a policy issued through IHC Portal. The cancellation will be initiated via IHC portal. See
the Sequence diagram for “IcCancelPolicy” method on Figure 10Figure 9.

Sequence Diagram

Figure 10: Sequence diagram for "IcCancelPolicy" Method

Request Parameters for “IcCancelPolicy” Method:

Parameter Type(Size) Sample Value Mandatory Data Description
SQL Type Source
PolicyRequestReferenceNo Alphanumeric(13) 1000255 YES IHC Each request from IHC system to IC API will have
Unique Policy Reference number generated by IHC
system.
InsuranceCompanyCode Numeric(3) 123 YES IC Insurance company Code provided by IHC. This
Smallint code is Not changeable. Each insurance company
will have its own and fixed Code.
RequestReferenceNo Alphanumeric(13) 323132 YES IHC Quote Request reference number generated by
IHC.
QuoteReferenceNo Numeric(15) 2006409 YES IC Unique reference number generated by Insurance
company system for each policy quote request

IHC– Auto Lease Integration Guide – Confidential Page | 64

 PolicyReferenceNo Numeric(10) 4654654 YES IC Policy Response Reference No generated by IC API
at the time of providing policy quote
PolicyNumber Alphanumeric(100) 13/60/XXX/2000- YES IC or IHC Policy number generated by Insurance Company
1128 system or IHC
LessorID Numeric(10) 7005454545 YES IC Company enterprise 700 Number (7XXXXXXXXX) as
Ministry of Commerce
LesseeID Numeric(10) XXXX943082 YES IC Lessee (Vehicle Owner) ID (National ID Number,
Iqama ID Number, or Computer Company ID).
National ID Number: 1XXXXXXXXX
Iqama ID Number: 2XXXXXXXXX
VehicleSequenceNumber Numeric(12) XXXX12345678 (if ”VehicleUniqueIDType” IC Vehicle Sequence Number which is written in the
= 1) registration Card (Istemarh) of vehicle
YES
else
null
VehicleCustomID Numeric(12) XXXX12345678 (if IC Vehicle custom Cardin case the vehicle imported or
”VehicleUniqueIDType”= still Not having a Registration Card (Istemarh)
2)
YES
else
null
IsCancelled Boolean True YES IC TRUE to cancel a policy, FALSE to undo a previous
mistaken cancellation

CancellationTime Alphanumeric(20) 2017-08-05 YES IC The Date & Time when policy get cancelled. (yyyy-
15:30:33 MM-dd HH:mm:ss)
CancellationReason Numeric(3) 12 YES IC Refer to CancellationReason master table for
Smallint supported values.
CustomizedParameter JSON Array NO IC Custom parameters array in case of additional
parameters required. Refer to
“CustomizedParameter” for further details.
5.10.1.1 CancellationReason
CancellationReasonID CancellationReasonEnglishName CancellationReasonArabicName

1 Car is a total loss ‫إسقاط اللوحة‬

2 Leasing Contract Termination ‫فسخ عقد االيجار‬

5.10.1.2 JSON Array Fields for “CustomizedParameter”

Parameter Type(Size) Sample Value Mandatory Description

IHC– Auto Lease Integration Guide – Confidential Page | 65

 SQL Type

Key Alphanumeric (50) Age YES Custom Parameter Key Name

Value1 Alphanumeric (50) 17 YES Custom Parameter Value One
Value2 Alphanumeric (50) 18 NO Custom Parameter Value Two
Value3 Alphanumeric (50) 19 NO Custom Parameter Value Three
Value4 Alphanumeric (50) 20 NO Custom Parameter Value Four

Response Parameters for “IcCancelPolicy” Method:

Parameter Type(Size) Sample Mandatory Data Description Validations
SQL Type Value source
RequestedCommission Numeric(8,2) 23.32 If ‘Status’ = IC The amount requested from IC based on the refunded
Float True, then amount.
YES else NO
RefundedAmount Numeric(8,2) 1323.32 If ‘Status’ = IC The amount that was refunded from IC to the client.
Float True, then
YES else NO
Status Boolean True YES IHC True: Success, It should match the
False: Failure DataType
errors JSON Array Refer Error Response Fields for more detail

IHC– Auto Lease Integration Guide – Confidential Page | 66

5.11 After Error codes
Following are the list of HTTP Error Codes will be used during processing any request during protocol level.

HTTP Error Code Name Description

400 Client or Validation error The HTTP request is incomplete or not in correct format.
The request is not according to standards agreed by both
the parties.
401 Authorization failure Authorization is required to use the service, but a valid
user name and password were not supplied.
403 Forbidden/Access denied You do not have permission perform this action.
404 Requested resource not found This status code is returned when the request contains
invalid service in the URL or an invalid URL itself. For
example, a service call returned with 404 HTTP status code
to let you know about resource is not exists.
405 Method not allowed The request method (POST or GET) is not allowed on the
requested resource.
406 Unsupported accept header Client has indicated with Accept headers that it will not
accept any of the available representations of the
resource.
407 Proxy authentication required The requested proxy requires authentication. The Proxy-
authenticate header contains the details of how to
perform the authentication.

408 Request timeout The maximum connection idle time was exceeded while
receiving the request.
409 Inconsistent/Conflicting state Request could not be carried out because of a conflict on
the server.
410 Unavailability of resource The requested resource is no longer available.
411 HTTP length required The server requires that the client include a Content-
Length specification in the request. This typically occurs
when uploading data to the server.

IHC– Auto Lease Integration Guide – Confidential Page | 67

 412 Pre-condition failed Pre-condition failed indicates that a condition set for this
request failed, and the request cannot be carried out.
Conditions are set with conditional request headers like If-
Match, If-none-Match, or If-Unmodified-Since.

413 Entity too large The request exceeds the maximum permitted size.
414 URI too large The length of the URI exceeds the maximum allowed
length.
415 Unsupported content type Indicates that the request is an unsupported type.
416 Requested range out of scope Indicates that the range of data requested from the
resource cannot be returned, either because the
beginning of the range is before the beginning of the
resource, or the end of the range is after the end of the
resource.
417 Expectation failed An expectation given in an Expect header could not be
met by the server.
500 Unexpected server error An unexpected server error occurred. The request could
not be processed. It indicates that error is at Tameeni side
and they will reach out to you and fix this ASAP.
501 not implemented The HTTP request method is not GET, HEAD, or POST.
502 Bad gateway The document requested resides on a third-party server
and the server received an error from the third-party
server.
503 Service unavailable The number of connections exceeds the allowed
maximum.
504 Gateway timeout Intermediate proxy server timed out while waiting for a
response from another proxy or the origin server.
505 HTTP version not supported Requested HTTP version is not supported by the server.

5.12 Error response fields

Field Description
field The request field that triggered this error. Applicable to HTTP 400 errors only.
message Detailed error message.
code Custom error code that is generated from machine to identify error field usability.

IHC– Auto Lease Integration Guide – Confidential Page | 68

5.13 Error codes (HTTP - 400)
In addition to the error message, the error response will also contain error code that is from machine to identify error field usability. The following table
lists the error codes and their descriptions.

Code Description
field_missing A Mandatory field is not found in the request.
invalid_input A value specified in the field is not valid value or not in proper format.
duplicate_error A field is expecting unique value between requests which founds duplicates.
invalid_field An unknown or additional field(s) specified in the request which was not expected.
invalid_json JSON request is Not well formed.
unexpected_error An Unexpected error occurred from server. Contact Tameeni and share request
details to investigate further.
authentication_failed Authentication with the service failed. Invalid username or password.
membership_expired The account membership expired or locked.

IHC– Auto Lease Integration Guide – Confidential Page | 69