No Claim Discount (NCD) - SOAP Service Integration

Najm for Insurance Services

No Claim Discount System- NCD 2.1

SOAP SERVICE INTEGRATION GUIDE
VERSION: [2.1]
Created By: IT Division (E-Solutions)

Version: 2.1 1
 No Claim Discount (NCD) - SOAP Service Integration

CONTENTS
CONTENTS ............................................................................................................................................................... 2
DOCUMENT CONTROL............................................................................................................................................. 3
Record of Changes ........................................................................................................................................... 3
INTRODUCTION ....................................................................................................................................................... 4
Overview and Objectives:................................................................................................................................. 4
Objective.......................................................................................................................................................... 4
Purpose............................................................................................................................................................ 4
NCD Solution Architecture....................................................................................................................................... 5
COMMUNICATIONS ................................................................................................................................................. 6
NCD Service ..................................................................................................................................................... 6
NCD SERVICE ARCHITECTURE .................................................................................................................................. 7
Inquiry for NCD eligibility ................................................................................................................................. 7
ERROR CODES & MESSAGES LOOK UP TABLE .........................................................................................................11
NCD YEARS CLAIM FREE LOOK UP TABLE ................................................................................................................11
CLIENT CONFIGURATION ....................................................................................................................................... 12
Appendix A: ........................................................................................................................................................... 13
SoapUI User Manual ...................................................................................................................................... 13
Appendix B: ........................................................................................................................................................... 21
Lookup Tables ................................................................................................................................................ 21
Data Dictionary: ............................................................................................................................................. 22
Appendix C: ........................................................................................................................................................... 23
Assumptions: ................................................................................................................................................. 23
Appendix D: ........................................................................................................................................................... 23

Version: 2.1 2
 No Claim Discount (NCD) - SOAP Service Integration

DOCUMENT CONTROL

Record of Changes
Version Author Date Description
1.0 Najm E-solution team 23/08/2018 Documents created

Version: 2.1 3
 No Claim Discount (NCD) - SOAP Service Integration

INTRODUCTION
Najm for Insurance Services (Najm) is providing a platform to facilitate the decision making for No Claim Discount
(NCD) Eligibility that has been regulated by SAMA in circular 161. That is mean Insurance Companies will be able to
integrate their underwriting engine with this service to get an instance result of NCD eligibility of their future policyholders
and drivers clients. Najm will provide this service to insurance companies to inquire about NCD through secured web
service. NCD Aggregation will be from insurance company side.

Overview and Objectives:

Objective
The objective of this document is to give integration guidelines to the insurance company technical team to
integrate with Najm NCD service including the needed inputs/outputs classes and related attributes.
Purpose

The purpose of this No Claim Discount [NCD] service is to provide a secure interface to Insurance companies, so
they can perform inquiry about no claim discount using the policyholder/driver and the vehicle to Najm and Najm will
revert with the response to them as per the request.

Version: 2.1 4
 No Claim Discount (NCD) - SOAP Service Integration

NCD Solution Architecture

1. NCD Service is hosted on Najm environment with Secured Layer (HTTPS).

2. Insurance companies will pass valid PersonID and identifier along with vehicleID in case of policyholder for NCD
inquiry.

3. Application will first connect to the service by providing valid credentials and then will pass valid parameters to
WCF Service.

4. WCF Service will authenticate credential passed by insurance company, then parse the request and build result in
XML Format.

Version: 2.1 5
 No Claim Discount (NCD) - SOAP Service Integration

COMMUNICATIONS
NCD Service

NCD WCF service is hosted and secured with SSL Certificate. Which means that all communication between NAJM
and insurance companies will go through Secure HTTP protocol (HTTPS). Insurance companies can communicate to WCF
service by providing a valid credential to service request which already provided by Najm.

Communication channel will be in XML.

- Service type: SOAP
- Request type: XML
- Response type: XML

URL of UAT service: http://portalserviceuat.najm.sa/NCDPhaseIITest/NCDService.svc

URL of Production service: https://portalservices1.najm.sa/NCDService/NCDService.svc

Version: 2.1 6
 No Claim Discount (NCD) - SOAP Service Integration

NCD SERVICE ARCHITECTURE

Inquiry for NCD eligibility
Insurance Company shall post a request to Najm to inquire for NCD eligibility by passing three mandatory fields.
Method Name: NCDEligibility()

Request Parameters for “NCDEligibility” Method:

Sr No Name Type Mandatory Description

1 PersonID Numeric Yes Policyholder ID who own the vehicle or
Named driver ID.
Validation:
PersonID should be in NIC format. It should
be for individual only. Corporate
policyholders (starts with 7) will not be
accepted.
2 VehicleIdentifier Numeric Yes Vehicle Identifier will be:
<1> for Sequence Number
<2> for Custom Card
<3> for Named Driver
3 VehicleId Numeric Yes IF In case inquire for policyholder IC have to
VehicleIdentifier pass Sequence Number/Custom Card based
= 1 or 2 ELSE No on the selected vehicle identifier.

Validation:
If Sequence Number:
Minimum 2 digits and Maximum 10 digits
value will be considered

“NCDEligibility” Method Request Samples:

- Request with vehicle Sequence Number

NCDRef.NCDServiceClient serviceClient = new NCDRef.NCDServiceClient();

serviceClient.ClientCredentials.UserName.UserName = "XXXXX";
serviceClient.ClientCredentials.UserName.Password = "XXXXX";

int vehicleIdentifier = 1;
long policyHolderId = 1020157XXX;
long vehicleId = 916921XXX; // Sequence No – Min 6 digits and Max 10 digits will be considered

string responseData = serviceClient.NCDEligibility(policyHolderId, vehicleIdentifier, vehicleId);

Version: 2.1 7
 No Claim Discount (NCD) - SOAP Service Integration

- Request with vehicle Custom Card

NCDRef.NCDServiceClient serviceClient = new NCDRef.NCDServiceClient();

serviceClient.ClientCredentials.UserName.UserName = "XXXXX";
serviceClient.ClientCredentials.UserName.Password = "XXXXX";

int vehicleIdentifier = 2;
long policyHolderId = 1020157XXX;
long vehicleId = 1269210XXX;

string responseData = serviceClient.NCDEligibility(policyHolderId, vehicleIdentifier, vehicleId);

- Request with Named Driver

NCDRef.NCDServiceClient serviceClient = new NCDRef.NCDServiceClient();

serviceClient.ClientCredentials.UserName.UserName = "XXXXX";
serviceClient.ClientCredentials.UserName.Password = "XXXXX";

int vehicleIdentifier = 3;
long personId = 1020157XXX;

string responseData = serviceClient.NCDEligibility(personId, vehicleIdentifier, null);

- Request XML

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:NCDEligibility>
<tem:PersonId>?</tem:PersonId>
<tem:VehicleIdentifier>?</tem:VehicleIdentifier>
<!--Optional:-->
<tem:VehicleId>?</tem:VehicleId>
</tem:NCDEligibility>
</soapenv:Body>
</soapenv:Envelope>

Version: 2.1 8
 No Claim Discount (NCD) - SOAP Service Integration

Response Parameters for “NCDEligibility” Method:

Sr Name Type Mandatory Description

No
StatusCode = ‘1’ (in case Success response)
1 StatusCode Numeric Yes
StatusCode = ‘2’ (in case Failure response)
Yes
If (“StatusCode” = 1) Reference Number generated by Najm system in case
Valid string will be the StatusCode = ‘1’.
2 NCDReference String
returned Format: NCD{DDMMYY}{SEQUENCE}
Else blank string will be Example: NCD16031720
returned
If (“StatusCode” = 1) This parameter represents NCD eligibility.
It will return eligibility Refer to “NCD Years Claim Free” for more information.
3 NCDFreeYears Numeric count
Else blank string will be
returned
Yes This is the error code in case the StatusCode = 2 refer to
If (“StatusCode” = 2) “Error code & messages” for more information.
Error Code will be
4 ErrorCode String
returned
Else blank string will be
returned
This is the error message in case the StatusCode = 2
refer to “Error code & messages” for more information.
Yes
If (“StatusCode” = 2) - Validation Error – It will contain validation error XML
Error message will be by validating input request parameters and return
5 ErrorMsg String
returned validation error.
Else blank string will be - Error – It will contain error XML with unexpected error
returned message.

See below example for Success and Failure Response.

- Success Response:
<ResponseData>
<StatusCode>1</StatusCode>
<NCDReference>NCD1603174</NCDReference>
<NCDFreeYears>1</NCDFreeYears>
<ErrorCode />
<ErrorMsg />
</ResponseData>

Version: 2.1 9
 No Claim Discount (NCD) - SOAP Service Integration

- Failure Response:
Example_1 Response:
<ResponseData>
<StatusCode>2</StatusCode>
<NCDReference />
<NCDFreeYears />
<ErrorCode>E107</ErrorCode>
<ErrorMsg>Invalid Policyholder ID</ErrorMsg>
</ResponseData>
Example_2 Response:
<ResponseData>
<StatusCode>2</StatusCode>
<NCDReference />
<NCDFreeYears />
<ErrorCode>E111</ErrorCode>
<ErrorMsg>Error in processing your request</ErrorMsg>
</ResponseData>

Version: 2.1 10
 No Claim Discount (NCD) - SOAP Service Integration

ERROR CODES & MESSAGES LOOK UP TABLE

No Claim Discount [NCD] Service Validation Messages for ErrorCode and ErrorMsg parameters
Message Code Message
E101 Invalid Credential
E102 Permission needed to access this method
E103 No Records Found
E104 Policyholder ID is missing
E105 Vehicle Identifier is missing
E106 Vehicle ID is missing
E107 Invalid Policyholder ID
E108 Corporate policyholder ID is NOT allowed
E109 Invalid Vehicle ID
E110 Invalid Vehicle Identifier
E111 Error in processing your request
E112 Driver ID is missing
E113 Eligibility Search not done
E114 Multiple future policy found

NCD YEARS CLAIM FREE LOOK UP TABLE

NCDYears value and its meaning

NCDFreeYears No of Claims
0 If customer has a claim within the last active policy or Insurance coverage is not continues (gap is
found between future policy and the previous one).
1 ‘1’ Year Free Claim
2 ‘2’ Year Free Claim
3 ‘3’ Year Free Claim
4 ‘4’ Year Free Claim
5 ‘5’ Year Free Claim
6 ‘1’ Claim in Year 1 (Applicable next year)
7 ‘1’ Claim in Year 2 (Applicable next year)
8 ‘1’ Claim in Year 3 (Applicable next year)
9 ‘1’ Claim in Year 4 (Applicable next year)
10 ‘1’ Claim in Year 5 (Applicable next year)
11 Not eligible due uninsured old vehicle
12 Bonus
13 Not eligible due gap found between policies
Note: For further details please refer to Appendix D

Version: 2.1 11
 No Claim Discount (NCD) - SOAP Service Integration

CLIENT CONFIGURATION
Below configuration is needed in web.config file when you reference NCD Service in your application. As a sample, we
have configured UAT URL of web service – it is required to be updated when we point to production.
<system.serviceModel>
<bindings>
<wsHttpBinding>
<binding name="WSHttpBinding_INCDService" closeTimeout="00:10:00"
receiveTimeout="00:10:00" maxBufferPoolSize="268435456" maxReceivedMessageSize="268435456">
<security mode="TransportWithMessageCredential">
<transport clientCredentialType="None" />
<message clientCredentialType="UserName" negotiateServiceCredential="true"
establishSecurityContext="false" algorithmSuite="Default" />
</security>
</binding>
</wsHttpBinding>
</bindings>
<client>
<endpoint address="http://portalserviceuat.najm.sa/NCDServiceII/NCDService.svc"
binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_INCDService"
contract="NCDRef.INCDService" name="WSHttpBinding_INCDService" />
</client>
</system.serviceModel>

Version: 2.1 12
 No Claim Discount (NCD) - SOAP Service Integration

Appendix A:
SoapUI User Manual
1. Click right on “Project” and select “New SOAP Project”

2. Name the “Project Name” for example “NCDTest”.

3. Enter WSDL URL shared by NAJM.

Version: 2.1 13
 No Claim Discount (NCD) - SOAP Service Integration

4. A method will be displayed under the project name you have already created above.
5. Right click on the project name and select “Show Project View” option.
6. Select third tab “WS-Security Configuration”.

Version: 2.1 14
 No Claim Discount (NCD) - SOAP Service Integration

Version: 2.1 15
 No Claim Discount (NCD) - SOAP Service Integration

7. Click the plus (+) sign and enter a name for the configuration for example “NajmNCDTest”.

Version: 2.1 16
 No Claim Discount (NCD) - SOAP Service Integration

8. Then click on the below plus (+) sign to add the WSS type and select “UserName” from the dropdown list.

9. Add the UserName and Password shared by Najm and select “PasswordText” as the password type.

Version: 2.1 17
 No Claim Discount (NCD) - SOAP Service Integration

10. Right click on “NCDEligibility” method and create new request.

11. Click on “AUTH” then “Add New Authentication”
12. Select “Basic” type.

Version: 2.1 18
 No Claim Discount (NCD) - SOAP Service Integration

13. Add the Username and Password shared by Najm and select the outgoing WSS the same configuration we have
created on point 7.

Version: 2.1 19
 No Claim Discount (NCD) - SOAP Service Integration

14. Click on “WA-A” and tick on the default options as illustrated on below screenshot.

Version: 2.1 20
 No Claim Discount (NCD) - SOAP Service Integration

Appendix B:

Lookup Tables

Vehicle Identifier Master

Table 1
Vehicle Identifier Value Vehicle Identifier
1 Sequence Number
2 Custom Card
3 DriverID

Status Code Master

Table 2
Status Code Value Status Code
1 Success
2 Failure

Version: 2.1 21
 No Claim Discount (NCD) - SOAP Service Integration

Data Dictionary:

The data dictionary contains standard definitions and specifications for all data objects and attributes in the data model. It
forms a common language between NCD and different stakeholders who will connect with.

Attribute Description
PersonID This attribute represents the policyholder ID who own the vehicle or Named
driver.
VehicleIdentifier This attribute represents the type of value of Vehicle Id field.
‘1’ means Sequence Number
‘2’ means Custom Card
‘3’ means Driver ID
VehicleID This attribute represents the "VehicleID" number which can be Sequence
Number or Custom Card based upon the value of VehicleIdentifier

Version: 2.1 22
 No Claim Discount (NCD) - SOAP Service Integration

Appendix C:

Assumptions:

 Service will only fulfill request if Username/Password are passed and user has permission for “NCD WCF Service”.
 Service will only accept valid parameters as per this document.
 Security certificate SSL is not required for client access to connect to the service.
 Client need to connect to WCF service which will be under secure layer (HTTPS).
 This service available for individual inquiries only (National/Iqama ID).
 Corporate IDs that starts with ‘7’ will not be accepted.

Appendix D:

Number of years with TPL NCD Comp. NCD

no claim Scale Scale
1 10% 15%
2 20% 25%
3 30% 35%
4 40% 50%
5 or more 50% 60%

Version: 2.1 23