Implementation manual for client communication with the web service.

Version	Date	Description	Author
1.0.0	2025-01-17	Initial version	Alexandru Marinica

1. Introduction

The Road Assistance API service allows the generation of offers, the issurance of policies, as well as the printing of corresponding documents.

All requests (except for authentication requests) must contain the "Token" parameter in the Header, which contains an authorization token (JWT) obtained through authentication endpoints using credentials provided by Life Is Hard SA (as OPERATOR).

Environments:

test/development: https://road-assistance-qa.api.lifeishard.ro / - this is a test environment, where are available latest changes
production: https://road-assistance.api.lifeishard.ro/

The examples and definitions of the methods and resources offered by the service can be viewed through the Swagger UI platform: https://app.swaggerhub.com/apis/Life-is-Hard3/road-assistance.api.lifeishard.ro/1.0.0#/

Access to both environments is restricted to whitelisted IPs. To gain access, you need to contact the sales team.

The credentials used in the testing environment are not functional in the production environment.

1.1. Implemented products

Insurer	Identifier
Eazy Insurer	insurer:eazy_insure
Grawe	insurer:grawe
Pointer	insurer: pointer

1.2. Workflow

Creating policy:

Authentication Obtain a JWT token using credentials provided by OPERATOR
Create offer the response includes the [offerId] – this id will be needed in the following requests
Transform offer to policy use [offerId] from the offer step for policy to get the policy data
Download documents use [offerId] from the offer step to get offer documents, and [policyId] from the transform policy step to get policy documents

1.3. Response types

The main structure of response is:

Parameter	Description
errors	An array containing all the error messages
correlation_id	An internal ID to track the error
data	Data related to the response / Additional data regarding the response.

The structure of the responses can be divided into two major categories: successful response and error response.

Success

Parameter	Description
status	200 - 299
data	(object)

Error

Parameter	Description
errors	array
status	400 - 500
data	(optional) Additional data

The validation messages are set by default in English. To change the language of the validation messages to Romanian, add the following parameter in the request header: Content-Language, with the value: ro.

2. Authentication

2.1. Authenticate account

Endpoint: POST /auth

This method is used to authenticate an account by account and password (provided by OPERATOR).

If the authentication was successful. The response will include a JSON object with the following properties:

data: A JSON object containing the following properties:
token: A string representing the JWT token generated by the server for the authenticated user.
expires_at: A string representing the date and time when the JWT token will expire in the format "YYYY-MM-DD HH:MM:SS".
refresh_token: A string representing the refresh token generated by the server for the authenticated user.

2.2. Renew token

Endpoint: PATCH /auth

This method is used to renew an authentication token based on the refresh token.

If the token has been successfully renewed, the generated response will have the same structure as the authentication response.

2.3. De-authenticate account

Endpoint: DELETE /auth

This method is used to de-authenticate an existing and valid auth token.

3. Create offer

Endpoint**:** POST /offer

3.1. Request

3.1.1. Input parameters

Parameter	Type	Required	Description	Validation rules
provider	object	Yes	Information related to the insurer
provider.organization	object	Yes	Insurer’s data
provider.organization.businessName	string	Yes	Insurer identifier (see 1.1 → Identifiers)
provider.authentication	object	Yes	Credentials to access insurer’s web service
provider.authentication.account	string	Yes	Account	Theese credentials will be provided by the OPERATOR
provider.authentication.password	string	Yes	Password
provider.authentication.code	string	No	Code
product	object	Yes	Information's related to the product
product.motor	object	Yes
product.motor.startDate	string	Yes	The effective date of the policy	• Accepted format: YYYY-MM-DD • The date can be current date ifproduct.vehicle.registrationType is one of [temporaryRegistered, temporaryRecorded] • The date has to be in the future if product.vehicle.registrationType is one of [registered, recorded]
product.motor.termTime	number	Yes	Policy validity in number of months	Values between 1 and 12
product	Person object	Yes	Policyholder’s data
product.vehicle	Vehicle object	Yes	Vehicle’s data
product.additionalData	object	No (depending on the product)	Must be completed according to the Product specific parameters section This structure can either be sent with product-specific parameters or with all parameters every time. Parameters sent in the plus will be ignored.

Person object

Parameter	Type	Required	Description	Validation rules
businessName	string	Yes if it is present in the request	Business name (if the person is a legal entity)
companyRegistrationNumber	string	Yes if it is present in the request	Company registration number (if the person is a legal entity)
caenCode	number	No	CAEN code (if the person is legal entity)
lastName	string	Yes if businessName field is not present	Individual person's last name
firstName	string	Yes if businessName field is not present	Individual person's first name
taxId	string	Yes	• Personal identification code for natural persons • Tax identification number for non-natural persons	It must be a valid Romanian CNP if businessName field is not present and isForeignPerson is false (or it’s not present)
isForeignPerson	boolean	No	Indicates if person is foreign person
nationality	string	Yes if isForeignPerson is true	Nationality	Accepted values: iso2 codes from /nomenclature/country nomenclature. No validation applied if legal entity.
citizenship	string		Citizenship	Accepted values: iso2 codes from /nomenclature/country nomenclature. No validation applied if legal entity.
gender	string		Gender: • m => male • f => female	Accepted values: m, f No validation applied if legal entity.
birthdate	string		Date of birth	• Accepted format: YYYY-MM-DD • The date must be in the past. • No validation applied if legal entity.
email	string	Yes	Email address	It must be a valid email address.
mobileNumber	string	No	Mobile phone number
identification	object	Yes if businessName field is not present	Information's related to the identification document	Information required for individual
identification.idType	string	Yes if identification field is present	Type of the identification document	Accepted values: CI, PASSPORT
identification.idNumber	string	Yes if identification field is present	Series and number of the identification document	It must be a valid Romanian ID number
identification.issueAuthority	string	No	Issuer of the identification document
identification.issueDate	string	No	Issuing date of the identification document	Accepted format: YYYY-MM-DD
address	Address object	Yes	Person’s home address

Address object

Parameter	Type	Required	Description	Validation rules
country	string	No	iso2 country code	Accepted values: iso2 codes from /nomenclature/country nomenclature
county	string	Yes	County code	Accepted values: any code from /nomenclature/county nomenclature
city	string	Yes	Locality name	Accepted values: any name from /nomenclature/locality/{cod_judet} nomenclature
cityCode	number	Yes	Locality code	Accepted values: any siruta code from /nomenclature/locality/{cod_judet} nomenclature
street	string	Yes	Street
houseNumber	string	Yes	House number
building	string	No	Building
staircase	string	No	Staircase
apartment	string	No	Apartment
floor	string	No	Floor
postcode	string	No	Postcode

Vehicle object

Parameter	Type	Required	Description	Validation rules
registrationType	string	Yes	Vehicles registration type	Accepted values: any codefrom /nomenclature/vehicle-typenomenclature
licensePlate	string	Yes, if registrationType is registered	Vehicles Romanian license plate	3.1.2. Validation rules point 1
vin	string	Yes	Vehicle identification number	• The value must be between 5 and 17 characters in length. • If the yearOfConstruction is after 1981, the characters O, I, and Q are excluded.
vehicleType	string	Yes		Accepted values: M1, M2, M3, N1, N2, N3, O1, O2, O3, O4, L1e, L2e, L3e, L4e, L5e, L6e, L7e, T, C, R, S, G
brand	string	Yes	Brand name	Accepted values: any name from /nomenclature/make nomenclature
model	string	Yes	Brand model name	Accepted values: any name from /nomenclature/model/{make_ws_id} nomenclature
yearOfConstruction	string	Yes	Vehicles production year	• format: YYYY • maximum value [current year] + 1
engineDisplacement	number	Yes	Engine cubic inch (CC)
enginePower	number	Yes	Engine power (kW)
totalWeight	number	Yes	Gross vehicle weight
seats	number	Yes	Number of seats
fuelType	string	Yes	Vehicle energy source	Accepted values: any codefrom /nomenclature/vehicle-fuel-typenomenclature
firstRegistration	string	No	First registration in Romania	Format: YYYY-MM-DD
usageType	string	Yes	Vehicle usage purpose	Accepted values: any codefrom /nomenclature/vehicle-usage-typenomenclature
identification	object	No
identification.idNumber	string	Yes	Vehicles identification number (CIV in Romania)	• 7 character length • first character is a letter • last 6 characters are digits
currentMileage	number	No	The current mileage of the vehicle in kilometers.
hasMobilityModifications	boolean	No	Indicating whether the vehicle has been modified for use by people with loco-motor disabilities.
isLeased	boolean	No	Indicating whether the vehicle has an active lease contract.
owner	Person object	Yes

3.1.2. Validation rules

The following validation rules are country specific, currently it is Romania specific.

The vehicle.licensePlate can have one of the following formatting rule based on the vehicle.registrationType:
vehicle.registrationType is registered
licensePlate is required
length between 3 and 8 characters (upper case and digits)
can start with county codes followed by 2 or 3 digits and 3 upper case letters 3 digits only apply to county code B Ex: B101AXB, B10AAA, CJ01LIH
the 3 letter part cannot start with I or O, cannot contain Q, cannot be III or OOO
vehicle.registrationType is temporaryRegistered
licensePlate is not required
no specific format validation applied

3.2. Response

The object structure returned in the data field is described in this section.

Parameter	Type	Description
provider	object
provider.organization	object
provider.organization.businessName	string	Insurer identifier
offers	array of Offer objects	A list of generated offers, which can include offers generated successfully and/or offers generated with errors.

Offer object (in case of successfully generated offer)

Parameter	Type	Description
offerId	number	Unique identifier of the offer.Use this to transform the offer into a policy.
providerOfferCode	string	Unique identifier of the offer generated by the insurer
premiumAmount	number	Premium amount defined in the currency returned in currency field
premiumAmountNet	number	Premium net amount defined in the currency returned in currency field
currency	string	Currency
startDate	string	The start date of the policy
endDate	string	The end date of the policy
referenceRate	number	Offer reference rate
bonusMalusClass	string	BM used to calculate premiumAmount
commissionValue	number	Commission value which will be received by the broker
commissionPercent	number	Commission percent used to calculate commissionValue
greenCardExclusions	string	List of countries where the policy will not applied
notes	string	Notes
offerExpiryDate	string	Format:Y-m-d
directCompensation	object	Offer information with direct compensation applied
directCompensation.providerOfferCode	string	Unique identifier of the offer generated by the insurer with direct compensation applied
directCompensation.premiumAmount	number	Premium amount with direct compensation defined in the currency returned in currency field
directCompensation.commissionValue	number	Commission value with direct compensation
directCompensation.commissionPercent	number	Commission percent with direct compensation
installments	object
installments.id	number	Number of the installment
installments.amount	number	Premium amount of the installment
installments.dueDate	string	Format:Y-m-d
pid	string	PID file url (filled only if configured - done by developer)
toc	string	Terms And Conditions file url(filled only if configured - done by developer)

Policyholder and vehicle.owner accepted combinations

policyholder	vehicle.owner	Acceptance criteria
Individual person (PF)	Individual person (PF)	Yes, if policyholder is the same as vehicle.owner and vehicle.isLeased is false
Individual person (PF)	Legal entity(PJ)	Yes
Legal entity(PJ)	Legal entity(PJ)	Yes • if vehicle.owner is a leasing company, vehicle.owner is different from policyholder and vehicle.isLeased is true • if policyholder is the same as vehicle.owner and vehicle.isLeased is false

4. Transform offer to policy

Endpoint: POST /policy

For repeated requests using the same offer ID, the response will return the policy that was saved during the first request. If the policy has already been issued, a new one will not be created.

4.1. Request

4.1.1. Input parameters

Parameter	Type	Required	Description
offerId	number	Yes	Unique identifier of the offer (offerId from Offer object)
payment	Payment object	Yes	Payment details
additionalData	object	No (depending on the product)	Must be completed according to the Product specific parameters section This structure can either be sent with product-specific parameters or with all parameters every time. Parameters sent in the plus will be ignored.

Payment object

Parameter	Type	Required	Description	Validation rules
method	string	Yes	Payment methodNote: not all products will accept every option	Accepted values: card de credit
currency	string	Yes	Payment currency	At the moment only RON is accepted
amount	number	Yes	The payment amount in RON
date	string	Yes	Payment date	Accepted format: YYYY-MM-DD
documentNumber	string	Yes	Payment proof document details

4.2. Response

The object structure returned in the data field is described in this section.

Parameter	Type	Description
policies	array of Policy objects	A list of issued policies, which can include policies successfully and/or with errors.

Policy object (in case of successfully issued policy)

Parameter	Type	Description
provider	object
provider.organization	object
provider.organization.businessName	string	Insurer identifier
policyId	number	Unique identifier of the issued policy
series	string	Policy series
number	number	Policy number
payment	ResponsePayment object
startDate	string	Policy start date
endDate	string	Policy end date
premiumAmount	number	Value of the policy
currency	string	Policy value currency
installments	object
installments.id	number	Number of the installment
installments.amount	number	Premium amount of the installment
installments.dueDate	date	Format:Y-m-d

ResponsePayment object

Parameter	Type	Description
method	string	Payment method sent to insurer (mapped to insurer’s payment methods)
currency	string	The currency in which the payment was made
amount	number	Paid amount
date	string	Payment date
documentNumber	string	Payment proof document details

5. Documents

5.1. Offer

Endpoint: GET /offer/{offerId}

This API endpoint enables users to download the offer in PDF format. You will need to provide the OfferID received from the offer request call to access the download feature.

5.2.1 Policy

Endpoint: GET /policy/\{policyId\}
Description: Downloads the policy in PDF format.

5.2.2 By policy series and number

Endpoint: GET /policy?series={series}&number={number}

You will need to provide the series and number received in the response of transform offer into policy call to access the download feature.

6. Product-specific parameters

This section of the implementation manual outlines the specifications for the additionalData object, which forms part of the request for bidding and transformation of offers into policies. The section also describes specific validation rules for each product.