ULIP Integration Document

ULIP Integration Document

Version No.: 4.0

Date: 01/10/2024

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, New Delhi, India.
 ULIP Integration Document

Revision History

Version Date Author Reviewer Significant Changes

1.0 09/07/2021 Hasan Mhad Khan Nayab Ali Baseline Version

Update Request
2.0 09/08/2022 Akshay Singh Nayab Ali
Body Regex
Added Fastag 02
3.0 14/03/2024 Ayush Arya Nayab Ali
API
4.0 01/10/2024 Ayush Arya Nayab Ali Updated

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 2 of 19
 ULIP Integration Document

Table of Contents

Introduction ................................................................................................................................................. 4
1.1 Purpose .................................................................................................................................... 4
The Overall Description .............................................................................................................................. 4
1.2 Data Integration between FASTAG System and ULIP application .......................................... 4
1.3 FASTAG/01 .............................................................................................................................. 4
1.3.1 Technical Approach .................................................................................................... 5
1.4 FASTAG/02 .............................................................................................................................. 8
1.4.1 Technical Approach .................................................................................................... 9
1.5 Data Transmission & Authentication Mechanism .................................................................. 17

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 3 of 19
 ULIP Integration Document

Introduction

1.1 Purpose

The purpose of this document is to define and provide details for accessing API for
transaction details from NETC Fastag (National Electronic Toll Collection) system from
ULIP system.
This document details the following points:

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

2. Technical Approach for performing Data Integration

The Overall Description

User will share the information such as vehicle registration number based on data send
by user ULIP system will call FASTag API for accessing information.

Following are the point for accessing vehicle information: -

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

2. ULIP will expose API for getting data from FASTAG API.

3. FASTAG/01 API will take vehicle registration number from user and get data from
FASTAG API.

1.2 Data Integration between FASTAG System and ULIP application

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

1.3 FASTAG/01

This API will take Vehicle registration number / Vehicle Chassis number and
connect with FASTAG API to get data.

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 4 of 19
 ULIP Integration Document

S. Field Name Field Description Format Required/No Length

No. t – Required

1 vehiclenumber Vehicle registration ^[A-Z0- Required (5 to 11) and

number / Vehicle 9]{5,11}$|^[A- (17 to 20)
Chassis number as Z0-9]{17,20}$
available in FASTAG
system.
1.3.1 Technical Approach
1. All the data will be shared through rest web services.
2. ULIP system will provide vehicle registration number / vehicle chassis number for
which detail is required.
3. FASTAG API will share details of vehicle transaction information which exist in FASTAG
system in JSON format.
4. ULIP system will provide the data in JSON Object format in response body.

NOTE: Data related to VRN will be available for the next 3 days.
Example: the first transaction happens on 1rd Jan (data will be available for 3rd Jan, on
4th Jan no data will be available regarding the previous transaction i.e. 1 st Jan)

Example:

Vehicle registration number GA060000 is shared by ULIP system, then FASTAG-

integration will make a request to FASTAG API.

Request:

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

For production -
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/FASTAG/01

{
"vehiclenumber": "GA060000"
}

Curl URL

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 5 of 19
 ULIP Integration Document

curl --location --request POST

'https://www.ulip.dpiit.gov.in/ulip/v1.0.0/FASTAG/01' \
--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjMwNTAyNDI1LCJhcH
BzIjoiZGF0YXB1c2gifQ.C7nHJJvr2h7UEufpnDOBUPkHCCCDoNtVg5iK5Dw7uE
gxqHYxJkPGnkoNcy02oj7JYHQzDcHfEpvbVenUMdvl_A' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"vehiclenumber": "GA060000"
}'

For staging -
https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/FASTAG/01

{
"vehiclenumber": "GA060000"
}

Curl URL

curl --location 'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/FASTAG/01' \

--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwMiIsImlhdCI6MTcyNzY5MDAwMCwi
YXBwcyI6ImRhdGFwdXNoIn0.2BrY8dCCS_BAH5Y6faXPYAPJEV52bGuZZRtK
XD04AOmAUtooBy9TC-wmWVvxyAWsqLR9ifBhYD9xfqGMDPH9_A' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"vehiclenumber": "UP15AU1291"
}'

For obtaining authentication token, refer Section 1.5

Response

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

a) In case of invalid format

1. Invalid vehicle number

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 6 of 19
 ULIP Integration Document

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: vehiclenumber.
Format should follow ^[A-Z0-9]{5,11}$|^[A-Z0-9]{17,20}$"
}

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

{
"response": [
{
"response": {
"result": "FAILURE",
"respCode": "000",
"ts": "2022-02-15T11:34:31",
"vehicle": {
"errCode": "740"
}
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

c) In case vehicle number exist

{
"response": [
{
"response": {
"result": "SUCCESS",
"respCode": "000",
"ts": "2021-11-01T19:20:47",
"vehicle": {
"errCode": "000",

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 7 of 19
 ULIP Integration Document

"vehltxnList": {
"totalTagsInMsg": "2",
"msgNum": "1",
"totalTagsInresponse": "2",
"totalMsg": "1",
"txn": [
{
"readerReadTime": "2021-10-30 12:26:09.0",
"seqNo": "68d47e2d-c10f-4f57-b12a-2dfb547ce5c8",
"laneDirection": "N",
"tollPlazaGeocode": "11.0001,11.0001",
"tollPlazaName": "GMR Chillakallu Toll Plaza",
"vehicleType": "VC7",
"vehicleRegNo": "MH19JK3923"
},
{
"readerReadTime": "2021-10-30 12:41:23.0",
"seqNo": "6361cf5f-8ddd-46dd-9593-0aa0e1fd5780",
"laneDirection": "N",
"tollPlazaGeocode": "11.0001,11.0001",
"tollPlazaName": "GMR Chillakallu Toll Plaza",
"vehicleType": "VC7",
"vehicleRegNo": "MH19JK3923"
}
]
}
}
},
"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
Status Code 502: Server is not responding.

1.4 FASTAG/02

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 8 of 19
 ULIP Integration Document

This API will take Vehicle registration number / tagid and connect with FASTAG API
to get data. We have to enter vehiclenumber or tagid for get the data.

S. Field Name Field Description Format Required/No Length

No. t – Required

1 vehiclenumber Vehicle registration ^[A-Z0- Optional (5 to 11) and

number / Vehicle 9]{5,11}$|^[A- (17 to 20)
Chassis number as Z0-9]{17,20}$
available in FASTAG
system.
2 tagid Tag id as available in ^[A-Z0- Optional (0 to 25)
FASTAG system. 9]{0,25}$

1.4.1 Technical Approach

5. All the data will be shared through rest web services.
6. ULIP system will provide vehiclenumber or tagid for which detail is required.
7. FASTAG API will share details of vehicle information which exist in FASTAG system in
JSON format.
8. ULIP system will provide the data in JSON Object format in response body.

NOTE: User have to enter vehiclenumber or tagid in request body. If user will enter both
vehiclenumber and tagid in request body, user will get the error response from Fastag
API. User have to enter one of these either vehiclenumber or tagid for get the
response.

Example:

Vehicle registration number MP09HF4987 or tag id 34161FA8203286140F4064E0 is

shared by ULIP system, then FASTAG-integration will make a request to FASTAG API.

Request:

The request must be of the following format, where vehiclenumber or tagid is passed within
the URL body in JSON format.

For production -
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/FASTAG/02

{
"vehiclenumber": "MP09HF4987",
"tagid": "34161FA8203286140F4064E0"

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 9 of 19
 ULIP Integration Document

}
-
Curl URL

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

--
header 'authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNzEwNDA
zOTEzLCJhcHBzIjoiZGF0YXB1c2gifQ.Bm3DOCwdDJ6z7_0nf4Vpse2LLYh_3ncSriXYmWqWIZzBWnOd9ICMNp
1ZglD8nE94SZQUhBPyLzdGLr4iNjjw9Q' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data-raw '{
"vehiclenumber": "MP09HF4987",
"tagid": "34161FA8203286140F4064E0"
}'

For staging -
https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/FASTAG/02

{
"vehiclenumber": "MP09HF4987",
"tagid": "34161FA8203286140F4064E0"
}
-
Curl URL
curl --location 'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/FASTAG/02' \
--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwMiIsImlhdCI6MTcyNzY5MDAwMCwiYXBwcyI6ImRhdGFwdXNoI
n0.2BrY8dCCS_BAH5Y6faXPYAPJEV52bGuZZRtKXD04AOmAUtooBy9TC-
wmWVvxyAWsqLR9ifBhYD9xfqGMDPH9_A' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"vehiclenumber": "MP09HF4987",
"tagid": "34161FA8203286140F4064E0"
}'

For obtaining authentication token, refer Section 1.5

Response

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

1. Invalid vehicle number

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 10 of 19
 ULIP Integration Document

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

2. Invalid tagid number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: tagid. Format should fo
llow ^[A-Z0-9]{0,25}$"
}

3. In case if we enter vehiclenumber or tagid null or empty

{
"response": [
{
"response": "vehiclenumber or tagid :must not be Empty or null, Please ent
er vehiclenumber or tagid",
"responseStatus": "ERROR"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

4. In case if we enter both vehiclenumber and tagid

{
"response": [
{
"response": {
"result": "FAILURE",
"successReqCnt": "0",
"totReqCnt": "1",

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 11 of 19
 ULIP Integration Document

"respCode": "239",
"ts": "2024-03-15T09:23:19",
"vehicle": {
"errCode": "239"
}
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

5. In case of vehiclenumber or tagid does not exist in FASTAG system

{
"response": [
{
"response": {
"result": "FAILURE",
"successReqCnt": "0",
"totReqCnt": "1",
"respCode": "239",
"ts": "2024-03-14T14:07:09",
"vehicle": {
"errCode": "239"
}
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

6. In case vehicle number exist

{
"response": [
{
"response": {
"result": "SUCCESS",

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 12 of 19
ULIP Integration Document

"successReqCnt": "1",
"totReqCnt": "1",
"respCode": "000",
"ts": "2024-03-14T14:07:48",
"vehicle": {
"errCode": "000",
"vehicledetails": [
{
"detail": [
{
"name": "TAGID",
"value": "34161FA820328972020FB320"
},
{
"name": "REGNUMBER",
"value": "MP09HF4987"
},
{
"name": "TID",
"value": "E20034120183C2FFEEB86B77"
},
{
"name": "VEHICLECLASS",
"value": "VC11"
},
{
"name": "TAGSTATUS",
"value": "I"
},
{
"name": "ISSUEDATE",
"value": "2017-07-14"
},
{
"name": "EXCCODE",
"value": "06"
},
{
"name": "BANKID",
"value": "607417"
},
{
"name": "COMVEHICLE",
"value": "T"

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 13 of 19
ULIP Integration Document

}
]
},
{
"detail": [
{
"name": "TAGID",
"value": "34161FA8203289720E14EEA0"
},
{
"name": "REGNUMBER",
"value": "MP09HF4987"
},
{
"name": "TID",
"value": "E20034120137FE0006D097ED"
},
{
"name": "VEHICLECLASS",
"value": "VC11"
},
{
"name": "TAGSTATUS",
"value": "I"
},
{
"name": "ISSUEDATE",
"value": "2019-01-09"
},
{
"name": "EXCCODE",
"value": "06"
},
{
"name": "BANKID",
"value": "607417"
},
{
"name": "COMVEHICLE",
"value": "T"
}
]
},
{

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 14 of 19
ULIP Integration Document

"detail": [
{
"name": "TAGID",
"value": "34161FA82033E764D9F45341"
},
{
"name": "REGNUMBER",
"value": "MP09HF4987"
},
{
"name": "TID",
"value": "34161FA82033E764D9F45341"
},
{
"name": "VEHICLECLASS",
"value": "VC11"
},
{
"name": "TAGSTATUS",
"value": "A"
},
{
"name": "ISSUEDATE",
"value": "2019-10-11"
},
{
"name": "EXCCODE",
"value": "00"
},
{
"name": "BANKID",
"value": "652210"
},
{
"name": "COMVEHICLE",
"value": "T"
}
]
}
]
}
},
"responseStatus": "SUCCESS"
}

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 15 of 19
 ULIP Integration Document

],
"error": "false",
"code": "200",
"message": "Success"
}

7. In case tag id exist

{
"response": [
{
"response": {
"result": "SUCCESS",
"successReqCnt": "1",
"totReqCnt": "1",
"respCode": "000",
"ts": "2024-03-14T14:09:07",
"vehicle": {
"errCode": "000",
"vehicledetails": [
{
"detail": [
{
"name": "TAGID",
"value": "34161FA8203286140F4064E0"
},
{
"name": "REGNUMBER",
"value": "MAT735701"
},
{
"name": "TID",
"value": "E2801105200088444B320B00"
},
{
"name": "VEHICLECLASS",
"value": "VC4"
},
{
"name": "TAGSTATUS",
"value": "A"
},
{
"name": "ISSUEDATE",

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 16 of 19
 ULIP Integration Document

"value": "2023-07-10"
},
{
"name": "EXCCODE",
"value": "00"
},
{
"name": "BANKID",
"value": "606986"
},
{
"name": "COMVEHICLE",
"value": "F"
}
]
}
]
}
},
"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
Status Code 502: Server is not responding.

1.5 Data Transmission & Authentication Mechanism

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

For production -
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/FASTAG/01

Body:

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 17 of 19
 ULIP Integration Document

{
"vehiclenumber": "GA060000"
}

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",
"password": "xxxx@123"
}'

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywiYXBwcyI6I
mRhdGFwdXNoIn0.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/FASTAG/01
\
-H 'accept: application/json' \

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 18 of 19
 ULIP Integration Document

-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywiYXBwcyI6I
mRhdGFwdXNoIn0.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": "GA060000" }'

For staging –

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

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

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNzI3MTYxMDgwLCJhcHBzIjoiZGF0
YXB1c2gifQ.XhVZm7NiCD05-
v9091WJQhYzdk1a0Shs_ley0T4R2MX63swRyxHbHxh6bVXtzqWvWiSLwwNGRQIcqGhr49hpGg

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 details as follow -

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

curl --location 'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/FASTAG/01' \

--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwMiIsImlhdCI6MTcyNzY5MDAwMCwiYXBwcyI6I
mRhdGFwdXNoIn0.2BrY8dCCS_BAH5Y6faXPYAPJEV52bGuZZRtKXD04AOmAUtooBy9T
C-wmWVvxyAWsqLR9ifBhYD9xfqGMDPH9_A' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"vehiclenumber": "UP15AU1291"
}'

Doc Ref. No: ULIP Integration Doc Version No: 4.0 Page 19 of 19