Implementation manual for client communication with the web service.

Version	Date	Description
1.1	2025-03-24	New endpoint: GET policy?series=\{series\}&number=\{number\}
1.0.0	2023-08-01	Initial version

API changelog: http://rotr-qa.api.lifeishard.ro/changelog

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

1.1. Implemented products

Insurer	Product	Identifiers
ABC Asigurari	ROT	Insurer: abcProduct: rotr
Phoenix	CMR	Insurer: phoenix Product: cmr
Phoenix	ROT	Insurer: phoenix Product: rot

- Products which are under development (there are not available in production)

1.2. Workflow

Creating policy:

1. Authentication obtain a JWT token using credentials provided by OPERATOR

2. Create offer the response includes the [offerID] – this id will be needed in the following requests

3. Transform offer into policy use [offerID] from the create offer step to get the policy data

4. Download documents use [offerID] from the create offer step to get offer documents, and [policyID] from the transform offer into policy step to get policy documents

1.3. Response types

The main structure of response is:

Parameter	Description
error	This indicates the type of response: false indicates success, and true indicates an error.
status	HTTP status
data	Data related to the response / Additional data regarding the response.
message	Error message

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

1.3.1. Success

Parameter	Description
error	false
status	200
data	(object)

1.3.2. Error

Parameter	Description
error	true
status	400 - 500
message	Error message
data	(optional) Additional data

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:

• error: A boolean indicating if an error occurred during the request. In this case, it will be false.

• status: An integer representing the status code of the response. In this case, it will be 200.

• 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. Deauthenticate account

Endpoint: DELETE /auth

This method is used to deauthenticate an existing and valid auth token.

3. Create offer

Endpoint: POST /offer

3.1. Request

Input parameters

Parameter	Type	Required	Description	Validation rules
provider	object	Yes	Informations 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	• in DEV / QA environment these fields can be sent empty to use default test credentials
provider.authentication.password	string	Yes	Password
provider.authentication.code	string	Yes	Code
product	object	Yes	Informations related to the product
product.name	string	Yes	Product identifier (see 1.1. → Identifiers)
product.currency	string	Yes	Currency	Accepted values: RON, EUR, USD
product.transport	Transport object	Yes	Informations related to the transport	Must be completed according to the Product-specific parameters section
product.customer	Person object	No	Contractor’s data
product.policyholder	Person object or an array of Person objects	Yes	Policyholder’s data
agreements	object	No
agreements.gdpr	boolean	No	Person agrees with the european GDPR
agreements.marketing	boolean	No	Person agrees with marketing policies

Transport object

Parameter	Type	Required	Description	Validation rules
startDate	string	Yes	The effective date of the policy	• Accepted format: YYYY-MM-DD • The date must current date or a date in the future.
termTime	number	No	Policy validity in number of months	• Values between 1 and 12 • Default value: 12
installmentCount	number	No	Number of installments	• Note: not all insurers accept installments
sumInsured	number	Yes	Sum insured
numberOfVehicles	number	Yes	Number of vehicles
mentions	string	No	Mentions
discount	number	No	Discount percentage

Person object

Parameter	Type	Required	Description	Validation rules
businessName	string	Yes if it is present in request	Business name (if the person is a legal entity)
companyRegistryNumber	string	No	Company registration number (if the person is a legal entity)
lastName	string	Yes if businessName field is not present	Individual person's last name
firstName	string		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
citizenship	string		Citizenship	Accepted values: iso2 codes from /nomenclature/country nomenclature
gender	string		Gender: • m => male • f => female	Accepted values: m, f
birthdate	string		Date of birth	• Accepted format: YYYY-MM-DD • The date must be in the past.
email	string	No	Email address	It must be a valid email address.
mobileNumber	string	No	Mobile phone number
identification	object	No	Informations related to the identification document
identification.idType	string	Yes	Type of the identification document	Accepted values: CI, PASSPORT
identification.idNumber	string	Yes	Series and number of the identification document
identification.issueAuthority	string	Yes	Issuer of the identification document
identification.issueDate	string	Yes	Issuing date of the identification document	Accepted format: YYYY-MM-DD
address	Address object	No	Person’s home address
correspondenceAddress	Address object	No	Person’s correspondence 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/{country_code} nomenclature
cityCode	number	Yes	Locality code	Accepted values: any siruta code from /nomenclature/locality/{country_code} 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	number	No	Postcode

Business rules

1. The contractor can be a legal entity or an individual over the age of 18

2. If the contractor is not specified, the first person in the 'insured' category over the age of 18 will be selected

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
product	object
product.name	string	Product identifier
offers	Offer object	Generated offer details

Offer object

Parameter	Type	Description
offerId	number	Unique identifier of the offer.Use this to transform the offer into a policy.
premiumAmount	number	Premium amount defined in the currency returned in currency field
currency	string	Currency
premiumRates	array of PremiumRate objects	List of premiumAmount expressed in other currencies
installments	array of Installment object
payment	object	Informations related to the payment
payment.amount	number	Amount that should be paid
payment.currency	string	The currency in which the payment should be made
startDate	string	The start date of the policy
endDate	string	The end date of the policy
productInformationDocument	string	URL to PID document
termsAndConditions	string	URL to insurance terms and conditions
notes	string	Notes
providerResponse	object	Insurer’s original response

PremiumRate object

Parameter	Type	Description
currency	string	Currency
amount	number	Amont
exchangeRate	number	Exchange rate

Installment object

Parameter	Type	Description
id	number	Number of the installment
currency	string	Currency
amount	number	Amount of the installment
dueDate	string	Due date of the installment

4. Get offer’s status

Endpoint: GET /offer/{id}/status

Get an existing offer's status. There is a call made to the insurer.

4.1. 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
product	object
product.name	string	Product identifier
offerNumber	string	Offer number
offerStatus	string	Offer’s status. Available statuses are pending, canceled, expired, refused, blocked, error, initialized, offered, transformed
insuredName	string	Insured name
offerCreationDate	string	Offer creation date
insuredAmount	number	Insured amount
premiumAmount	number	Premium 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

5. Transform offer into policy

5.1. Request

Input parameters

Parameter	Type	Required	Description
offerId	number	Yes	Unique identifier of the offer (offerId from Offer object)
payment	Payment object	Yes	Payment details

Payment object

Parameter	Type	Required	Description	Validation rules
method	string	Yes	Payment methodNote: not all products will accept every option	Accepted values: receipt, broker receipt, payment order, broker payment order, pos
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

5.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

Parameter	Type	Description
provider	object
provider.organization	object
provider.organization.businessName	string	Insurer identifier
product	object
product.name	string	Product 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	array of Installment object
providerResponse	object	Insurer’s original response

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

6. Documents

6.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 in the response of create offer call to access the download feature.

6.2. Policy

This API endpoint enables users to download the policy in PDF format.

6.2.1 By policy identifier

Endpoint: GET /policy/{PolicyID}

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

6.2.2 By policy series and number

Endpoint: GET /policy?seriex={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.

7. Product-specific parameters

This section of the implementation manual outlines the specifications for the product.transport object which forms part of the create offer request. The section also describes specific validation rules for each product.

7.1. ABC Asigurari - ROT

Create offer - product.additionalData object

Parameter	Type	Required	Description
product	object	Yes
product.transport	object	Yes
product.transport.sumInsuredRRA	number	Yes	Limit of liability requested by the Romanian Road Authority

Business rules

1. Insurance period is 1 year.

2. In the offer request the only accepted currency is EUR.

3. product.transport.sumInsured must be greater than or equal to product.transport.sumInsuredRRA

4. This product accepts only 1 policyholder.

5. Home address is mandatory (policyholder.*.address and customer.address - if customer is present in request)

6. If policyholder.*.address.country is not specified the default value is set to RO.

7. In order to transform an offer into a policy it is necessary to accept the terms and conditions by accessing the QR code found in the PDF of the offer

8. The PDF of the offer is available only for approved offers.

9. Only active offers can be transformed into policies.

Auxiliary methods

Get pending offer’s data

If an offer is pending (it needs to be approved, it needs to be confirmed or it is active) then this endpoint returns informations about it:

• endpoint POST /abc/rotr/pending-offer

• Swagger documentation: https://app.swaggerhub.com/apis/Life-is-Hard3/rotr.api.lifeishard.ro/1.0.0#/Auxiliary%20methods/getPendingOffer

7.2. Phoenix - CMR

Create offer - product.additionalData object

Parameter	Type	Required	Description EN	Description RO	Validation rules
product	object	Yes
product.transport	object	Yes
product.transport.issuerEmail	string	Yes	Issuer’s email address	Adresa de email a emitentului
product.transport.eventLiabilityLimit	number	Yes	Total liability limit per event	Limită răspundere totală per eveniment	• Must be equal with sum insured (product.transport.sumInsured)
product.transport.transportLicenseNo	string	Yes	Transport license number	Număr licență transport
product.transport.additionalRequests	string	No	Additional requests	Solicitări adiționale
product.transport.previousClaims	boolean	No	Claims in the last 3 years	Există cereri de despăgubire în ultimii 3 ani	• Default value: false
product.transport.includeInsurerPremiumStatement	boolean	No	Includes insurer's first loss statement	Include decont de primă asigurator	• Default value: false
product.transport.vehicles	array of Vehicle object	Yes			• Must contain a number of vehicles declared in product.transport.numberOfVehicles parameter
product.transport.insuredOtherThanLegalPerson	boolean	No	Insured other than legal entity (sole trader, individual enterprise)	Asigurat diferit de PJ (PFA, Intreprindere individuală)	• Default value: false
product.transport.theftRisk	boolean	No	Additional theft clause	Clauza suplimentară furt	• Default value: false
product.transport.refrigeratingAggregatesDamageRisk	boolean	No	Additional clause for damage to refrigerated units	Clauza suplimentară Avarii la agregate frigorifice	• Default value: false
product.transport.cabotageRisk	boolean	No	Additional clause for cabotage operations carried out in EU countries	Clauza suplimentară Operațiuni de cabotaj efectuate în statele UE	• Default value: false
product.transport.handlingRisk	boolean	No	Additional loading/unloading operations clause	Clauza suplimentară Operațiuni încărcare/descărcare	• Default value: false
product.transport.undeclaredVechileRisk	boolean	No	Additional clause for undeclared vehicles to the insurer (per tractor unit insurance)	Clauza suplimentară Vehicule nedeclarate asiguratorului (asigurare per cap-tractor)	• Default value: false
product.transport.uniqueTransport	boolean	No	Single Transit Insurance	Asigurare Transport Unic	• Default value: false
product.transport.noClaimsRenewal	boolean	No	No-claims renewal	Reînnoire fără daune	• Default value: false
product.transport.deductible	boolean	No	Optional deductible	Franșiză opțională	• Default value: false
product.transport.vehicleLiabilityLimitExceedsAuthority	boolean	No	One of the vehicles exceeds the liability limit of 150,000 Euro	Unul dintre vehicule depășește limita de răspundere de 150.000 Eur	• Default value: false
product.transport.roadRoute	string	Yes if uniqueTransport is true	Single Transit route	Traseu Transport Unic
product.transport.otherTransportedGoods	string	No	Goods other than those listed	Alte bunuri decât cele listate
product.transport.containerInsuredSum	number	Yes if transportedGoods contains id 12 (Containere)	Insured amount per container	Suma asigurată per container
product.transport.noOfContainers	number	Yes if transportedGoods contains id 12 (Containere)	Number of containers	Număr de containere	• The number of containers must be less than or equal to the number of vehicles.
product.transport.transportedGoods	array	Yes	Categories of transported goods	Categorii bunuri transportate	• Accepted values: any Id from /nomenclature/phoenix/cmr/transported-goods nomenclature
product.transport.containsTractorUnits	boolean	No	The fleet of insured vehicles contains tractor units.	Lista de autovehicule contine autotractoare	Boolean Value

Vehicle object

Parameter	Type	Required	Description	Validation rules
vin	string	Yes	Vehicle’s identification number	• 17 characters length • no I, O or Q characters
brand	string	Yes	Brand name	• Accepted values: any MakeName from /nomenclature/phoenix/cmr/vehicles-makes nomenclature
model	string	Yes	Brand model name
licensePlate	string	Yes	Vehicles' Romanian license plate
liabilityLimit	number	Yes	Vehicle’s liability limit	The sum of the vehicle liability limits must be equal to the total sum insured.
vehicleTypeId	number	Yes	Vehicle type id	• Accepted values: any id from /nomenclature/phoenix/cmr/vehicles-types

Business rules

1. Accepted currencies (product.currency) are RON and EUR

2. Maximum accepted vehicle number (product.transport.numberOfVehicles) is 100

3. Accepted values for product.transport.installmentCount are 1, 2, 3 and 4.

4. This product accepts only 1 policyholder.

5. Policyholder must be a legal person.

6. Home address is mandatory (policyholder.*.address and customer.address - if customer is present in request)

7. Total liability limit per event (product.additionalData.product.transport.eventLiabilityLimit) must be equal with sum insured (product.transport.sumInsured)

8. The vehicle list (product.additionalData.product.transport.vehicles) must contain a number of vehicles declared in product.transport.numberOfVehicles parameter.

9. In case of unique transport (product.additionalData.product.transport.uniqueTransport = true) the information sent in product.transport.termTime parameter is considered number of days (instead of number of months). In this case the maximum accepted value for policy validity is 60 days.

10. Minimum sum insured value is 10 000 EUR.

11. If number of containers (product.additionalData.product.transport.noOfContainers) and insured amount per container (product.additionalData.product.transport.containerInsuredSum) are defined then total sum insured is calculated as follows:

totalSumInsured = sumInsured + noOfContainers * containerInsuredSum

12. The number of containers (product.additionalData.product.transport.noOfContainers) must be less than or equal to the number of vehicles (product.transport.numberOfVehicles).

13. Under certain conditions, the offer may require the approval of EUROINS INSURANCE Bulgaria AD. The reasons why the offer may require approval are:

• Another type of insurance - PFA, individual company

• Goods category: Other Transported Goods

• Goods category: Motor vehicles/vehicles and machinery not subject to oversized transport

• Goods category: Goods subject to bulk transport/heavy loads and/or industrial loads

• Goods category: Container

• Risk of damage to the refrigerating units

• Cabotage risk

• Vehicle risk

• Number of validity months less than or equal to 2 if it is not a single transport

• Claims for compensation - claims for compensation in the last 3 years

• Discount request higher than the established limit

• Limit per vehicle greater than 150,000 euros

• Additional requests entered

14. In case of approval or rejection of the offer, a notification will be sent to the issuer's email address

Business rules

1. Payment method receipt is not accepted for this product.

Nomenclatures

1. Transported goods nomenclature - /nomenclature/phoenix/cmr/transported-goods

2. Vehicle makes nomenclature - /nomenclature/phoenix/cmr/vehicles-makes

7.3. Phoenix - ROT

Create offer - product.additionalData object

Parameter	Type	Required	Description EN	Description RO	Validation rules
product	object	Yes
product.transport	object	Yes
product.transport.issuerEmail	string	Yes	Issuer’s email address	Adresa de email a emitentului
product.transport.eventLiabilityLimit	number	Yes	Total liability limit per event	Limită răspundere totală per eveniment	• Must be equal with sum insured (product.transport.sumInsured)
product.transport.transportLicenseNo	string	Yes	Transport license number	Număr licență transport
product.transport.additionalRequests	string	No	Additional requests	Solicitări adiționale
product.transport.previousClaims	boolean	No	Claims in the last 3 years	Există cereri de despăgubire în ultimii 3 ani	• Default value: false
product.transport.includeInsurerPremiumStatement	boolean	No	Includes insurer's first loss statement	Include decont de primă asigurator	• Default value: false
product.transport.vehicles	array of Vehicle object	No			• If at least one vehicle is specified, the list must contain a number of vehicles declared in product.transport.numberOfVehicles parameter
product.transport.fixedQuota	number	No	Requested preferential rate (if broker has approved discount range)	Cotă preferențială solicitată (dacă brokerul are interval de reducere aprobat)
product.transport.capitalAndReserves	number	No	Insured's share capital + reserves	Valoare capital social + rezervele asiguratului

Vehicle object

Parameter	Type	Required	Description	Validation rules
vin	string	Yes	Vehicle’s identification number	• 17 characters length • no I, O or Q characters
brand	string	Yes	Brand name	• Accepted values: any MakeName from /nomenclature/phoenix/rot/vehicles-makes nomenclature
model	string	Yes	Brand model name
licensePlate	string	Yes	Vehicles' Romanian license plate
liabilityLimit	number	Yes	Vehicle’s liability limit	The sum of the vehicle liability limits must be equal to the total sum insured.

Business rules

1. Accepted currencies are RON and EUR

2. Maximum accepted vehicle number is 100

3. Accepted values for product.transport.installmentCount are 1, 2, 3 and 4.

4. This product accepts only 1 policyholder.

5. Policyholder must be a legal person.

6. Home address is mandatory (policyholder.*.address and customer.address - if customer is present in request)

7. Total liability limit per event (product.additionalData.product.transport.eventLiabilityLimit) must be equal with sum insured (product.transport.sumInsured)

8. The vehicle list (product.additionalData.product.transport.vehicles) must contain a number of vehicles declared in product.transport.numberOfVehicles parameter.

9. Under certain conditions, the offer may require the approval of EUROINS INSURANCE Bulgaria AD. The reasons why the offer may require approval are:

• Number of validity months less than 12 – Subannual insurance

• Claims for compensation - claims for compensation in the last 3 years

• Discount greater than the allowed limit

• Period limit greater than 100,000 euros

• Requested preferential rate (outside the approved range)

• Additional requests entered

10. In case of approval or rejection of the offer, a notification will be sent to the issuer's email address

Business rules

1. Payment method receipt is not accepted for this product.

2. Payment date must be a date before or equal to the current date.

Nomenclatures

1. Vehicle makes nomenclature - /nomenclature/phoenix/rot/vehicles-makes