Version: 0.2.0

Bilforsikring (Car Insurance)

API Documentation for Car Insurance integration with the Consumer Council's insurance service.

Request from Consumer Council

When the Consumer Council sends a request to the insurance company, it will be in JSON format. This request contains information about the person to be insured, as well as details about the specific offer that has been requested. The request will be sent to the company's specified endpoint.

The information about the person to be insured will be built based on data from the National Registry, the Norwegian Public Roads Administration, and OFV.

In the header, we will include X-RequestId which is unique, and X-ClientId which will be finansportalen.

Missing match between Financial Portal Insurance and Companies' value limits

Where amount limits and values in the Financial Portal Insurance calculator must be selected as alternatives in the user interface, and the Insurance Company does not operate with the same limits in their price tariffs, the Insurance Company shall nevertheless return a price. The price shall be returned in the form of the nearest value to the customer's benefit, for example the nearest price at the nearest higher mileage.

Example Request

{
    "id": "string",
    "person": {
        "pid": "string",
        "firstName": "string",
        "lastName": "string",
        "addresses": [
            {
                "source": "string",
                "streetName": "string",
                "postalCode": "string",
                "postalLocation": "string"
            }
        ],
        "memberships": [
            {
                "membershipId": "string",
                "membershipName": "string"
            }
        ]
    },
    "offerRequest": [
        {
            "id": "string",
            "type": "bil",
            "data": {
                "coverage": "string",
                "addons": ["leiebil", "maskinskade"],
                "bonus": "string",
                "yearlyMileage": 0,
                "youngestDriver": 0,
                "loan": false,
                "currentMileage": 0,
                "currentAccidents": 0,
                "lastAccidentDate": "string",
                "deductible": 0,
                "carOwner": {
                    "ownerType": "string",
                    "leasingCompanyOrg": "string",
                    "otherOwner": {
                        "pid": "string",
                        "firstName": "string",
                        "lastName": "string"
                    }
                },
                "car": {
                    "source": "ofv",
                    "regNumber": "string",
                    "registrationDate": "2023-01-01",
                    "structureNo": "4360005000112020000",
                    "variantId": 419436,
                    "vehicleGroup": "Personbil",
                    "modelYear": 2024,
                    "brandName": "Tesla",
                    "brandCode": 4360,
                    "modelName": "Model Y",
                    "modelCode": 5,
                    "modelGeneration": "1",
                    "modelSplitName": null,
                    "variantName": "Long Range AWD",
                    "variantCode": 11,
                    "segment": "SUV mellomklasse",
                    "chassisShortName": "SUV",
                    "chassis": "Sport Utility Vehicle",
                    "transmissionShortName": "AUT",
                    "transmission": "Automat",
                    "energySourceShortName": "E",
                    "energySource": "Elektrisitet",
                    "totalEngines": 2,
                    "emissionStandard": "Euro 6",
                    "importPrice": 471587,
                    "currencyCode": "NOK",
                    "approved": "2024-10-16T12:06:00Z",
                    "transferred": "2024-10-16"
                }
            }
        }
    ],
    "requestAt": "2024-10-16T12:06:00Z"
}

Request Field Descriptions

Root Level Fields

Field	Type	Description
`id`	string	The unique ID for the request
`requestAt`	string	The date and time when the request was sent. ISO 8601 (complete). Example: `"2024-10-16T12:06:00Z"` or `"2024-10-16T11:06:00+01:00"`

Person Object

Field	Type	Description
`pid`	string	The personal identification number of the person to be insured. Example: `"01019612345"`
`firstName`	string	The first name of the person to be insured. Example: `"Ole"`
`lastName`	string	The last name of the person to be insured. Example: `"Nordmann"`
`addresses`	array	Information about the address of the person to be insured
`memberships`	array	Information about various memberships of the person to be insured. Can be an empty list

Address Object

Field	Type	Description
`source`	string	Source of the address. Example: `"National Registry"`
`streetName`	string	Street name of the address. Example: `"Ole Nordmanns Gate 1"`
`postalCode`	string	Postal code of the address. Example: `"0123"`
`postalLocation`	string	Postal location of the address. Example: `"OSLO"`

Membership Object

Field	Type	Description
`membershipId`	string	The ID of the membership. Example: `"MEMB-001"`
`membershipName`	string	The name of the membership. Example: `"Tekna"`

Offer Request Object

Field	Type	Description
`id`	string	The unique ID for the request for an offer on this product
`type`	string	Type of product. Value: `"bil"`
`data`	object	Data for the offer

Offer Data Object

Field	Type	Description
`coverage`	string	Coverage for the insurance. Values: `"ansvar"`, `"delkasko"`, `"kasko"`, `"utvidet"`
`addons`	array	Additional services for the insurance. Can be an empty list. Values: `"leiebil"`, `"maskinskade"`
`bonus`	string	Bonus for the insurance. Example: `"75% > 5 år"`
`yearlyMileage`	integer	Annual mileage. Example: `10000`
`youngestDriver`	integer, nullable	Age of the youngest driver. Example: `22`
`loan`	boolean	Whether there is a loan on the car. Example: `false`
`currentMileage`	integer	Current mileage. Example: `45000`
`currentAccidents`	integer	Number of accidents. Example: `0`
`lastAccidentDate`	string	Date of the last accident. Example: `"2024-10-16"`
`deductible`	integer	Deductible for the insurance. Example: `5000`

Car Owner Object

Field	Type	Description
`ownerType`	string	Type of owner. Values: `"sameAsPerson"`, `"otherOwner"`, `"leasing"`
`leasingCompanyOrg`	string, optional/nullable	Organization number for leasing company. Example: `"123456789"`
`otherOwner`	object, optional/nullable	Information about another owner

Other Owner Object

Field	Type	Description
`pid`	string	Personal identification number of another owner. Example: `"987654321"`
`firstName`	string	First name of another owner. Example: `"Alice"`
`lastName`	string	Last name of another owner. Example: `"Wonderland"`

Car Object

Information about the car to be insured. Data with source "ofv" is not available for vehicles retrieved from "tenor" in the test environment.

Field	Type	Description
`source`	string	Source of car data. Values: `"ofv"`, `"tenor"` (only in test environment)
`regNumber`	string, optional/nullable	Registration number of the car. Example: `"AB12345"`
`registrationDate`	date	Date of first registration. Source: ofv. Example: `"2023-01-01"`
`structureNo`	string	Structure number for the car. Source: ofv. Example: `"4360005000112020000"`
`variantId`	integer	Variant ID for car model. Source: ofv. Example: `419436`
`vehicleGroup`	string	Vehicle group. Source: ofv. Example: `"Personbil"`
`modelYear`	integer	Model year of the car. Source: ofv. Example: `2025`
`brandName`	string	Brand name of the car. Source: ofv. Example: `"Tesla"`
`brandCode`	integer	Brand code of the car. Source: ofv. Example: `4360`
`modelName`	string	Model name of the car. Source: ofv. Example: `"Model Y"`
`modelCode`	integer	Model code of the car. Source: ofv. Example: `5`
`modelGeneration`	string	Model generation of the car. Source: ofv. Example: `"1"`
`modelSplitName`	string, nullable	Additional model specification. Source: ofv. Example: `"Sportwagon"`
`variantName`	string	Variant name for car model. Source: ofv. Example: `"Long Range AWD"`
`variantCode`	integer	Variant code for car model. Source: ofv. Example: `11`
`segment`	string	The segment the car belongs to. Source: ofv. Example: `"SUV mellomklasse"`
`chassisShortName`	string	Chassis code for the car. Source: ofv. Example: `"SUV"`
`chassis`	string	Chassis description for the car. Source: ofv. Example: `"Sport Utility Vehicle"`
`transmissionShortName`	string	Code for transmission. Source: ofv. Example: `"AUT"`
`transmission`	string	Type of transmission. Source: ofv. Example: `"Automat"`
`energySourceShortName`	string	Code for energy source. Source: ofv. Example: `"E"`
`energySource`	string	Type of energy source. Source: ofv. Example: `"Elektrisitet"`
`totalEngines`	integer	Number of engines. Source: ofv. Example: `2`
`emissionStandard`	string	Emission class. Source: ofv. Example: `"Euro 6"`
`importPrice`	integer	Import price of the car. Source: ofv. Example: `471587`
`currencyCode`	string	Currency code for import price. Source: ofv. Example: `"NOK"`
`approved`	string	Time of approval. ISO 8601 (complete). Source: ofv. Example: `"2024-10-16T12:06:00Z"`
`transferred`	string, nullable	Time of transfer. ISO 8601 (date only). Source: ofv. Example: `"2024-10-16"`

Multiple Offers Request

If the request contains multiple offers, the request will look like this. Here, an additional offer (offerRequest) has been added for each unique car:

{
    "id": "string",
    "person": {
        "pid": "string",
        "firstName": "string",
        "lastName": "string",
        "addresses": [
            {
                "source": "string",
                "streetName": "string",
                "postalCode": "string",
                "postalLocation": "string"
            }
        ],
        "memberships": [
            {
                "membershipId": "string",
                "membershipName": "string"
            }
        ]
    },
    "offerRequest": [
        {
            "id": "678aufj",
            "type": "bil",
            "data": {
                "coverage": "ansvar",
                "addons": ["leiebil", "maskinskade"],
                "bonus": "string",
                "yearlyMileage": 0,
                "youngestDriver": 0,
                "loan": false,
                "currentMileage": 0,
                "currentAccidents": 0,
                "lastAccidentDate": "string",
                "deductible": 0,
                "car": {
                    "source": "string",
                    "regNumber": "string"
                }
            }
        },
        {
            "id": "asdf43",
            "type": "bil",
            "data": {
                "coverage": "kasko",
                "addons": ["leiebil", "maskinskade"],
                "bonus": "string",
                "yearlyMileage": 0,
                "youngestDriver": 0,
                "loan": false,
                "currentMileage": 0,
                "currentAccidents": 0,
                "lastAccidentDate": "string",
                "deductible": 0,
                "car": {
                    "source": "string",
                    "regNumber": "string"
                }
            }
        }
    ],
    "requestAt": "2024-10-16T12:06:00Z"
}

Tenor Test Data Request

In the test environment, there may also be requests with vehicles from Tenor's dataset. These do not contain information from the OFV database:

{
    "id": "string",
    "person": {
        "pid": "string",
        "firstName": "string",
        "lastName": "string",
        "addresses": [
            {
                "source": "string",
                "streetName": "string",
                "postalCode": "string",
                "postalLocation": "string"
            }
        ],
        "memberships": [
            {
                "membershipId": "string",
                "membershipName": "string"
            }
        ]
    },
    "offerRequest": [
        {
            "id": "string",
            "type": "bil",
            "data": {
                "coverage": "string",
                "addons": ["leiebil", "maskinskade", "veihjelp"],
                "bonus": "string",
                "yearlyMileage": 0,
                "youngestDriver": 0,
                "loan": false,
                "currentMileage": 0,
                "currentAccidents": 0,
                "lastAccidentDate": "string",
                "deductible": 0,
                "carOwner": {
                    "ownerType": "string",
                    "leasingCompanyOrg": "string",
                    "otherOwner": {
                        "pid": "string",
                        "firstName": "string",
                        "lastName": "string"
                    }
                },
                "car": {
                    "source": "tenor",
                    "regNumber": "string"
                }
            }
        }
    ],
    "requestAt": "2024-10-16T12:06:00Z"
}

Allowed Values

Certain fields in the car insurance API have predefined values. Below are the allowed values for each of these special fields:

Bonus Values

Description	API Value
75% > 5 years	`75% > 5 år`
75% > 4 years	`75% > 4 år`
75% > 3 years	`75% > 3 år`
75% > 2 years	`75% > 2 år`
75%	`75%`
70% > 5 years	`70% > 5 år`
70% > 4 years	`70% > 4 år`
70% > 3 years	`70% > 3 år`
70% > 2 years	`70% > 2 år`
70%	`70%`
60%	`60%`
50%	`50%`
40%	`40%`
30%	`30%`
20%	`20%`
10%	`10%`
0%	`0%`
-10%	`-10%`
-20%	`-20%`
-30%	`-30%`
-40%	`-40%`

Membership Values

Description	API Value
LO Favor	`LO Favør`
Tekna	`Tekna`
Akademikerne	`Akademikerne`
NAF	`NAF`
Turistforeningen	`Turistforeningen`

Yearly Mileage Values

Description	API Value
5000km	`5000`
7000km	`7000`
10000km	`10000`
12000km	`12000`
16000km	`16000`
20000km	`20000`
25000km	`25000`
30000km	`30000`
40000km	`40000`
50000km	`50000`
Unlimited	`0`

Deductible Values

Description	API Value
1000kr	`1000`
2000kr	`2000`
3000kr	`3000`
4000kr	`4000`
5000kr	`5000`
6000kr	`6000`
8000kr	`8000`
10000kr	`10000`
12000kr	`12000`
14000kr	`14000`
16000kr	`16000`
20000kr	`20000`
25000kr	`25000`
30000kr	`30000`
35000kr	`35000`

Youngest Driver Age Values

Description	API Value
24 years or older	`24`
23 years	`23`
22 years	`22`
21 years	`21`
20 years	`20`
19 years	`19`
18 years	`18`

Response from Insurance Company

This is a description of how the response from the insurance company should be structured.

Example Response

{
    "id": "string",
    "company": "string",
    "totalPrice": 0,
    "totalDiscount": 0,
    "totalOriginalPrice": 0,
    "discountDescription": "string",
    "basePrice": 0,
    "products": [
        {
            "id": "string",
            "type": "string",
            "productName": "string",
            "prices": {
                "price": 0,
                "discount": 0,
                "originalPrice": 0,
                "tfa": 0.0
            },
            "productDetails": {
                "coverage": "string",
                "ipidUrls": [
                    {
                        "url": "string"
                    }
                ],
                "termsUrls": [
                    {
                        "url": "string"
                    }
                ]
            },
            "offer": {
                "bonus": "20%",
                "deductible": 0,
                "yearlyMileage": 0
            }
        }
    ],
    "purchaseUrl": "string",
    "receivedAt": "string",
    "responseAt": "string"
}

Response Field Descriptions

Root Level Fields

Field	Type	Description
`id`	string	The unique ID for the request for an offer on this product
`company`	string	The name of the insurance company. Example: `"Forsikringsselskap"`
`totalPrice`	integer	Total price for all products after discount. Example: `4500`
`totalDiscount`	integer	Total discount for all products. Example: `200`
`totalOriginalPrice`	integer	Total original price for all products before discount. Example: `4700`
`discountDescription`	string	Description of the discount that has been given. Example: `"Loyalty discount applied"`
`basePrice`	integer	Base price that is included in the calculation of the total price given. Example: `0`
`purchaseUrl`	string, optional/nullable	URL for purchasing the products. Example: `"https://example.com/purchase"`
`receivedAt`	string	Time when the request was received. ISO 8601 (complete). Example: `"2024-10-16T12:06:00Z"`
`responseAt`	string	Time when the response was sent. ISO 8601 (complete). Example: `"2024-10-16T12:06:00Z"`

Products Array

Field	Type	Description
`id`	string	The unique ID for the product. Example: `"123456789"`
`type`	string	Type of product (car, travel, house, home contents). Example: `"bil"`
`productName`	string	The name of the product. Example: `"Bilforsikring"`

Prices Object

Field	Type	Description
`price`	integer	Price for the product after discount
`discount`	integer	Discount for the product
`originalPrice`	integer	Original price for the product before discount
`tfa`	decimal	TFA fee for the product

Product Details Object

Field	Type	Description
`coverage`	string	Coverage for the product
`ipidUrls`	array	List of URLs to IPID documents (Insurance Product Information Document). Important: URLs must be direct download links that do not change
`termsUrls`	array	List of URLs to terms and conditions for the product

Offer Object

Field	Type	Description
`bonus`	string	Bonus for the product
`deductible`	integer	Deductible for the product
`yearlyMileage`	integer	Annual mileage for car product

Error Handling

In case of errors, the company should respond with an appropriate HTTP status code and the following body:

{
    "error": {
        "code": "string",
        "message": "string"
    }
}

Technical Error Codes

Code	Description
`validation_error`	Invalid or missing fields in the request
`failed_calculating_price`	The system was unable to calculate a price due to an internal error - for example, an internal calculation failure or missing data from the Consumer Council
`service_unavailable`	The service is temporarily unavailable (e.g., due to maintenance or capacity issues)
`unknown_error`	Unexpected error that does not fit into the other categories

Business Error Codes

Code	Description
`no_price_available`	The company cannot offer a price and would not have provided one in its public web solution either - for example, because the combination of parameters is not supported
`existing_agreement`	The company does not return a price because the user already has an existing agreement for the given product with the company
`additional_information_required`	The request requires more information; the user must contact an advisor

Request from Consumer Council​

Example Request​

Request Field Descriptions​

Root Level Fields​

Person Object​

Address Object​

Membership Object​

Offer Request Object​

Offer Data Object​

Car Owner Object​

Other Owner Object​

Car Object​

Multiple Offers Request​

Tenor Test Data Request​

Allowed Values​

Bonus Values​

Membership Values​

Yearly Mileage Values​

Deductible Values​

Youngest Driver Age Values​

Response from Insurance Company​

Example Response​

Response Field Descriptions​

Root Level Fields​

Products Array​

Prices Object​

Product Details Object​

Offer Object​

Error Handling​

Technical Error Codes​

Business Error Codes​

Request from Consumer Council

Example Request

Request Field Descriptions

Root Level Fields

Person Object

Address Object

Membership Object

Offer Request Object

Offer Data Object

Car Owner Object

Other Owner Object

Car Object

Multiple Offers Request

Tenor Test Data Request

Allowed Values

Bonus Values

Membership Values

Yearly Mileage Values

Deductible Values

Youngest Driver Age Values

Response from Insurance Company

Example Response

Response Field Descriptions

Root Level Fields

Products Array

Prices Object

Product Details Object

Offer Object

Error Handling

Technical Error Codes

Business Error Codes