ULIP Integration Requirement Document

ULIP Integration Requirement Document

Version No.: 1.0

Date: 02/07/2021

Project Name: ULIP

This document contains proprietary information of NLDSL. Unauthorized access, copying and replication are
prohibited. This document must not be copied in whole or part by any means, without the written authorization
of NLDSL, Noida, India.
 ULIP Integration Requirement Document

Revision History

Version Date Author Reviewer Significant Changes

1.0 02/07/2021 Hasan Mhad Khan Baseline Version

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 2 of 15
 ULIP Integration Requirement Document

Table of Contents

Introduction ................................................................................................................................................. 4
1.1 Purpose .................................................................................................................................... 4
The Overall Description .............................................................................................................................. 4
1.2 Data Integration between VAHAN System and ULIP application ............................................ 4
1.3 VAHAN/01 ................................................................................................................................ 5
1.3.1 Technical Approach ..................................................................................................... 5
1.4 VAHAN/02 ................................................................................................................................ 8
1.4.1 Technical Approach ..................................................................................................... 8
1.5 VAHAN/03 .............................................................................................................................. 11
1.5.1 Technical Approach ................................................................................................... 11
1.6 Data Transmission & Authentication Mechanism .................................................................. 14

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 3 of 15
 ULIP Integration Requirement Document

Introduction

1.1 Purpose

The purpose of this document is to define and provide details for accessing API for vehicle
information from ULIP system.
This document details the following points:

1. Data Integration between VAHAN and ULIP web service: Identification of operational
points where data integration between VAHAN and ULIP web service will be needed.

2. Technical Approach for performing Data Integration

The Overall Description

User will share the vehicle information such as vehicle number, chassis number and
engine number based on data send by user ULIP system will call respective VAHAN
APIs for accessing information.

Following are the point for accessing vehicle information: -

1. This API will share vehicle data based on information provided by user.

2. ULIP will expose three API for getting data from VAHAN API.

3. For VAHAN/01 ULIP will take vehicle number from user and get data from vahan API
based on vehicle number.

4. For VAHAN/02 ULIP will take chassis number from user and get data from vahan API
based on chassis number.

5. For VAHAN/03 ULIP will take engine number from user and get data from vahan API
based on engine number.

1.2 Data Integration between VAHAN System and ULIP application

User will share information to ULIP system based on data shared ULIP will provide data
to user.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 4 of 15
 ULIP Integration Requirement Document

1.3 VAHAN/01

This API will take vehicle number and connect with VAHAN API to get data.

S. No. Field Name Field Description Format Require Length

d/Not –
Require
d
1 vehiclenumber Vahicle Number as available [A-Z]{2}[0-9]{2}[A- Required 9
in VAHAN system Z]{0,5}[0-9]{4}$
XXNNXNNNN
X-> Alphabets
N-> Numeric

1.3.1 Technical Approach

1. All the data will be shared through rest web services.
2. ULIP system will provide vehicle number for which detail is required.
3. VAHAN API will share details of vehicle which exist in VAHAN system in xml format.
4. Data receive from VAHAN is in XML format. ULIP system convert this data to string format
and assign it to key “response”.
5. ULIP system will provide the data in JSON Object format in response body.

Example:

User will share Vehicle Number XX12X2345 to ULIP system, then ULIP system will
make a request to VAHAN API.

Request:

The request must be of the following format, where vehicle number is passed within the URL
body in JSON format.

https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/01

{
"vehiclenumber": "XX12X3456"
}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/01 \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 5 of 15
 ULIP Integration Requirement Document

-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIyNDQxMCwi
YXBwcyI6ImRhdGFwdXNoIn0.STkF5e_NKQeiv7Kyu6rRRRYMisrEbQwUjZbJzoi
2u-1LNH2oTsJQToVytU8FCQua6xzJNnIE5IFT9Bh2CLFugA' \
-H 'content-type: application/json' \
-d '{
"vehiclenumber": "XX12X3456"
}'

For obtaining authentication token, refer Section 1.6

Response

To acknowledge the above request, ULIP will send the below response -

a) In case of invalid format

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: vehiclenumber.
Format should follow [A-Z]{2}[0-9]{2}[A-Z]{0,5}[0-9]{4}$"
}

b) In case of vehicle number does not exist in VAHAN system

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n <stautsMessage>Vehicle Data Not
Found</stautsMessage>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 6 of 15
 ULIP Integration Requirement Document

"message": "Success"
}

c) In case vehicle exist

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n
<stautsMessage>OK</stautsMessage>\n
<rc_regn_no>UP91L0001</rc_regn_no>\n <rc_regn_dt>26-Jan-
2017</rc_regn_dt>\n <rc_owner_name>RAHUL KUMAR</rc_owner_name>\n
<rc_present_address>VIVEK NAGAR, NEAR MEHAR KOTHI, HAMIRPUR, -
999999</rc_present_address>\n <rc_permanent_address>VIVEK NAGAR,
NEAR MEHAR KOTHI, HAMIRPUR, -999999</rc_permanent_address>\n
<rc_vh_class_desc>M-Cycle/Scooter(2WN)</rc_vh_class_desc>\n
<rc_chasi_no>ME4JF509AH7069705</rc_chasi_no>\n
<rc_eng_no>JF50E76069768</rc_eng_no>\n <rc_maker_desc>HONDA
MOTORCYCLE AND SCOOTER INDIA (P) LTD</rc_maker_desc>\n
<rc_fuel_desc>PETROL</rc_fuel_desc>\n <rc_color>P A WHITE</rc_color>\n
<rc_fit_upto>25-Jan-2032</rc_fit_upto>\n <rc_tax_upto>25-01-
2032</rc_tax_upto>\n <rc_insurance_comp>HDFC ERGO General Insurance
Company Ltd</rc_insurance_comp>\n
<rc_insurance_policy_no>2320100501934300000</rc_insurance_policy_no>\n
<rc_insurance_upto>15-Sep-2020</rc_insurance_upto>\n
<rc_manu_month_yr>1/2017</rc_manu_month_yr>\n <rc_status_as_on>02-
Jul-2021</rc_status_as_on>\n
<rc_status>ACTIVE</rc_status>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle data response

Status Code 400: Bad request (Invalid json syntax, invalid json key)
Status Code 401 or 403: Unauthenticated or Unauthorized
Status Code 500: Some internal server error occurred

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 7 of 15
 ULIP Integration Requirement Document

Status Code 502: Server is not responding.

1.4 VAHAN/02

This API will take vehicle number and connect with VAHAN API to get data.

S. No. Field Name Field Description Format Require Length

d/Not –
Require
d
1 chasisnumber Chassis Number as available ^[a-zA-Z0- Required 17
in VAHAN system 9]{1,17}$

1.4.1 Technical Approach

1. All the data will be shared through rest web services.

2. ULIP system will provide chassis number for which detail is required.
3. VAHAN API will share details of vehicle which exist in VAHAN system in xml format.
4. Data receive from VAHAN is in XML format. ULIP system convert this data to string format
and assign it to key “response”.
5. ULIP system will provide the data in JSON Object format in response body.

Example:

Chassis Number MA6MFBC1BBT096358 is shared by ULIP system, then VAHAN-

integration will make a request to VAHAN API.

Request:

The request must be of the following format, where chassis number is passed within the URL
body in JSON format.

https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/02

{
"chasisnumber": "MA6MFBC1BBT096358"
}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/02 \
-H 'accept: application/json' \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 8 of 15
 ULIP Integration Requirement Document

-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIyNDQxMCwi
YXBwcyI6ImRhdGFwdXNoIn0.STkF5e_NKQeiv7Kyu6rRRRYMisrEbQwUjZbJzoi
2u-1LNH2oTsJQToVytU8FCQua6xzJNnIE5IFT9Bh2CLFugA' \
-H 'content-type: application/json' \
-d '{
"chasisnumber": "MA6MFBC1BBT096358"
}'

For obtaining authentication token, refer Section 1.6

Response

To acknowledge the above request, ULIP will send the below response –

a) In case of invalid format

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: chasisnumber.
Format should follow ^[a-zA-Z0-9]{1,17}$"
}

b) In case of chassis number does not exist in VAHAN system

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n <stautsMessage>Vehicle Data Not
Found</stautsMessage>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}
Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 9 of 15
 ULIP Integration Requirement Document

c) In case of chassis number exist

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n
<stautsMessage>OK</stautsMessage>\n
<rc_regn_no>MH14DA1845</rc_regn_no>\n <rc_regn_dt>11-Oct-
2011</rc_regn_dt>\n <rc_owner_name>PRASAD
DHOKE</rc_owner_name>\n <rc_present_address>SHILPA PALACE NR
VITTHAL MANDIR, AKURDI, PUNE, Pune-411035</rc_present_address>\n
<rc_permanent_address>SHILPA PALACE NR VITTHAL MANDIR, AKURDI,
PUNE, Pune-411035</rc_permanent_address>\n <rc_vh_class_desc>Motor
Car(LMV)</rc_vh_class_desc>\n
<rc_chasi_no>MA6MFBC1BBT096358</rc_chasi_no>\n
<rc_eng_no>B10S1710099KC2</rc_eng_no>\n <rc_maker_desc>GENERAL
MOTORS INDIA PVT LTD</rc_maker_desc>\n
<rc_fuel_desc>PETROL/CNG</rc_fuel_desc>\n <rc_color>S
GREY</rc_color>\n <rc_fit_upto>10-Oct-2026</rc_fit_upto>\n
<rc_tax_upto>LTT</rc_tax_upto>\n <rc_insurance_comp>BAJAJ
ALLIANZ</rc_insurance_comp>\n <rc_insurance_policy_no>OG-21-2042-
1805-00000086</rc_insurance_policy_no>\n <rc_insurance_upto>06-Dec-
2021</rc_insurance_upto>\n
<rc_manu_month_yr>3/2011</rc_manu_month_yr>\n <rc_status_as_on>02-
Jul-2021</rc_status_as_on>\n
<rc_status>ACTIVE</rc_status>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle data response

Status Code 400: Bad request (Invalid json syntax, invalid json key)
Status Code 401 or 403: Unauthenticated or Unauthorized
Status Code 500: Some internal server error occurred

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 10 of 15
 ULIP Integration Requirement Document

Status Code 502: Server is not responding.

1.5 VAHAN/03
This API will take engine number and connect with VAHAN API to get data.

S. No. Field Name Field Description Format Require Length

d/Not –
Require
d
1 enginenumber Engine Number as available ^[a-zA-Z0- Required 12
in VAHAN system 9]{1,12}$

1.5.1 Technical Approach

1. All the data will be shared through rest web services.
2. ULIP system will provide chassis number for which detail is required.
3. VAHAN API will share details of vehicle which exist in VAHAN system in xml format.
4. Data receive from VAHAN is in XML format. ULIP system convert this data to string format
and assign it to key “response”.
5. ULIP system will provide the data in JSON Object format in response body.

Example:

Engine Number K12MN4490060 is shared by ULIP system, then VAHAN-integration will

make a request to VAHAN API.

Request:

The request must be of the following format, where vehicle number is passed within the URL
body in JSON format.

https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/03

{
"enginenumber": "K12MN4490060"
}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/03 \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 11 of 15
 ULIP Integration Requirement Document

-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywi
YXBwcyI6ImRhdGFwdXNoIn0.rhumwWJ8BWeeHe9CYmIV1UKyJk-
kLHA_ovX5Zi2OwxEv-td-KpxnfbKDI_8FZsOoggqx3Al-Du1y2qMoUD7uzA' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 9cb5ac3c-59dd-4505-0b69-a03c07e59f26' \
-d '{
"enginenumber": "K12MN4490060"
}'

For obtaining authentication token, refer Section 1.6

Response

To acknowledge the above request, ULIP will send the below response –

a) In case of invalid format

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: enginenumber.
Format should follow ^[a-zA-Z0-9]{1,12}$"
}

b) In case of engine number does not exist in VAHAN system

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n <stautsMessage>Vehicle Data Not
Found</stautsMessage>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 12 of 15
 ULIP Integration Requirement Document

"message": "Success"
}

c) In case of engine number exist

{
"response": [
{
"response": "<?xml version=\"1.0\" encoding=\"UTF-8\"
standalone=\"yes\"?>\n<VehicleDetails>\n
<stautsMessage>OK</stautsMessage>\n
<rc_regn_no>KL03AD2548</rc_regn_no>\n <rc_regn_dt>29-Dec-
2018</rc_regn_dt>\n <rc_owner_name>THOMAS T V</rc_owner_name>\n
<rc_present_address>THEKKECHARUVIL HOUSE, PAYYANAMON,
KONNITHAZHAM,PATHANAMTHITTA, -0</rc_present_address>\n
<rc_permanent_address>THEKKECHARUVIL HOUSE, PAYYANAMON,
KONNITHAZHAM PATHANAMTHITTA, -689692</rc_permanent_address>\n
<rc_vh_class_desc>Motor Car(LMV)</rc_vh_class_desc>\n
<rc_chasi_no>MA3EWB22SJL604806</rc_chasi_no>\n
<rc_eng_no>K12MN4490011</rc_eng_no>\n <rc_maker_desc>MARUTI
SUZUKI INDIA LTD</rc_maker_desc>\n
<rc_fuel_desc>PETROL</rc_fuel_desc>\n <rc_color>NEXA BLUE
STARGAZE</rc_color>\n <rc_fit_upto>28-Dec-2033</rc_fit_upto>\n
<rc_tax_upto>30-09-2033</rc_tax_upto>\n
<rc_insurance_comp></rc_insurance_comp>\n
<rc_insurance_policy_no></rc_insurance_policy_no>\n
<rc_insurance_upto></rc_insurance_upto>\n
<rc_manu_month_yr>11/2018</rc_manu_month_yr>\n <rc_status_as_on>02-
Jul-2021</rc_status_as_on>\n
<rc_status>ACTIVE</rc_status>\n</VehicleDetails>\n",
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle data response

Status Code 400: Bad request (Invalid json syntax, invalid json key)

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 13 of 15
 ULIP Integration Requirement Document

Status Code 401 or 403: Unauthenticated or Unauthorized

Status Code 500: Some internal server error occurred
Status Code 502: Server is not responding.

1.6 Data Transmission & Authentication Mechanism

All data exchange would be done over secure HTTP (HTTPS). Request from ULIP's system would
be made in VAHAN system through a data exchange URL that has following form:

https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/<sequence number>

Body:

For VAHAN/01
{
"vehiclenumber": "UP91L0001"
}

For VAHAN/02
{
"chasisnumber": "MA6MFBC1BBT096358"
}

For VAHAN/03
{
"enginenumber": "K12MN4490011"
}

Access to above data exchange URL would be authorized by use of a security mechanism
implemented by the ULIP system. It is as follows:

• First time access: It would require a username and password [which would be shared with
user beforehand]. Once user hit with valid user id and password, ULIP system will return a
basic authorization token to user, using that token user will communicate with ULIP system
until token will not get expired.

Brief summary of HTTP Basic Authentication is as follows:

First time when User will hit ULIP secured API through username and password for access token
as follow-

curl --location --request POST 'https://www.ulip.dpiit.gov.in/ulip/v1.0.0/user/login' \

--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "xxxx",

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 14 of 15
 ULIP Integration Requirement Document

"password": "xxxx@123"
}'

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywiYXBwcyI6ImRh
dGFwdXNoIn0.rhumwWJ8BWeeHe9CYmIV1UKyJk-kLHA_ovX5Zi2OwxEv-td-
KpxnfbKDI_8FZsOoggqx3Al-Du1y2qMoUD7uzA'

Upon successful authentication, the user would be logged into the ULIP system and get an access
token. Though this token user can communicate with ULIP. This token has expiry time which
represent user session. The session time out for the same to be fixed hour, generally it is for 30
minutes. If there is no request coming from user for 30 minutes, then session (token) will be
expired and user need to re authenticate.

Using The above token, user can request ULIP system for vehicle details as follow -

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/VAHAN/01 \
-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywiYXBwcyI6ImRh
dGFwdXNoIn0.rhumwWJ8BWeeHe9CYmIV1UKyJk-kLHA_ovX5Zi2OwxEv-td-
KpxnfbKDI_8FZsOoggqx3Al-Du1y2qMoUD7uzA' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 8e8a19a4-ea1e-6373-f616-e2e4af9a1338' \
-d '{
"vehiclenumber": "UP91L0001"
}'

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 15 of 15