Overview
The Valuation endpoint is a RESTful web service, providing users with a replacement cost estimation for local and reporting currencies and a Value Adequacy assessment value (e.g., Over Insured, Low Risk, Medium Risk, or High Risk).
Authentication
The Kroll Property Insurance Valuation API is authenticated using an API Key. API keys must be obtained by contacting the Kroll Property Insurance Valuation team.
When you have received your API key make sure to keep it in a secure environment, as API keys do not expire.
API keys are never stored.
Users must include the API key in the HTTP header for every call, in order to authenticate the call.
If an API key is misplaced a new one must be issued by the Kroll Property Insurance Valuation team.
Protocols and Headers
The Property Insurance Valuation API uses POST request and HTTP response codes to indicate status and errors. The API uses HTTPS TLS v1.2. Calls made using HTTP and HTTPS TLS versions below 1.2 are not supported.
In addition to the authentication header, all requests must be made using HTTPS, including a content-type header of application/json and the payload body must be in JSON format.
All API responses are returned using JSON.
Header Structure:
- Curl Example:
curl -X POST {{baseURL}}/building/riskbenchmark\
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
- Postman® Example:
HTTP Response Codes and Errors
The Property Insurance Valuation API uses standard HTTP response codes to indicate the success or failure of an API request. Common response codes are listed below:
| Response Code | Description |
| 200 - OK | The request was successful. |
| 400 - Bad Request | The server could not understand the request due to an invalid parameter or syntax. |
| 401 - Unauthorized |
The client is not authenticated, and the response was not completed. |
| 403 - Forbidden | The client does not have permission to access the content. |
| 500 - Internal Server Error | An internal error occurred. |
| 503 - Service Unavailable | The server cannot currently handle the request. |
An error message will occur if required parameters are missing from the API request.
- Example:
"\"localCurrency\" is required"
Parameters
| Parameter | Field | Required | Type | Details |
| declaredValue | Declared Value | True (Yes) | Numeric |
Declared value is the total cost of rebuilding the property (between 1 - 50,000,000). If the Declared Value exceeds 50,000,000, the endpoint will return a 400 error, suggesting seeking an expert evaluation. |
| localCurrency | Local Currency | True (Yes) | String | Local Currency uses a 3-digit ISO 4217 currency code. |
| country | Country Name | True (Yes) | String | Country uses a 2-digit ISO 3166-1 alpha-2 country code. |
| postalCode | Postal Code/Zip Code | True (Yes) | String | Accepts the Postal Code/Zip Code using a string. |
| buildingType | Building Type | True (Yes) | Id | Building Type uses building type IDs provided as integers. |
| grossFloorArea | Gross Floor Area | True (Yes) | Numeric |
The Gross Floor Area is calculated by multiplying the building's footprint by the number of floors (including the basement). The Gross Floor Area is an integer greater than or equal to 0. |
| listed | Listed | True (Yes) | Bool |
Listed indicates if the building is listed as a historical or heritage building. If the building is listed = TRUE If the building is not list = FALSE |
| floors | Number of Floors | True (Yes) | Numeric |
The number of floors within the building from the ground floor up, provided as an integer between 1 - 15. If the floors exceed 15 the endpoint will return a 400 error, suggesting seeking an expert evaluation. |
| buildingFootprintArea | Building Footprint Area | False (No) | Numeric |
The Building Footprint Area is the land the building covers with its exterior walls. The Building Footprint Area is an integer greater than or equal to 0. |
| areaUnits | Area Units | Fales (No) | String |
The unit of measurement used for Gross Floor Area and Footprint Area. Area Unit values are square feet or square meters. If provided in payload will return results based on provided areaUnits. If left blank the system will default to square meters. |
| region | Region | False (No) | Id |
Regions represent different districts within a larger city. Region IDs correspond to the selected Country Code. Currently, regions are only available for US, GB, NL, DE, and CO. |
| buildingTotalHeight | Building Total Height | False (No) | Numeric |
The Building Total Height is calculated by measuring from the highest point to the lowest point of the building. The Building Total Height is an integer greater than or equal to 0. |
| averageFloorHeight | Average Floor Height | False (No) | Numeric |
The Average Floor Height is calculated by dividing the building's total height by the number of floors, with an integer between 0 and 15. If the Average Floor Height exceeds 15 the endpoint will return a 400 error, suggesting seeking an expert evaluation. |
| heightUnits | Height Units | False (No) | String |
The unit of measurement used for the Buildings Total Height and Average Floor Height. Height Unit values are feet or meters. If left blank the system will default to meters. |
| wallType | Wall Type | False (No) | Id |
Wall Type accepts Wall Type IDs provided as integers. |
| frameType | Frame Type | False (No) | Id |
Frame Type accepts Frame Type IDs provided as integers. |
| sprinklerCoverage | Sprinkler Coverage % | False (No) | Numeric |
The percentage of the building that the sprinkler system covers, with a minimum integer of 0 and a maximum value of 100. |
| reportingCurrency | Reporting Currency | False (No) | String |
The Reporting Currency. The Reporting Currency uses a 3-digit ISO 4217 currency code. |
| buildingQuality | Building Quality | False (No) | String |
Building Quality accepts the values LOW, AVG, or HIGH. If no Building Quality is provided the endpoint will default to Avg. |
Parameter Payload Structure
{
"declaredValue": 123456,
"localCurrency": "",
"country": "",
"region": 1,
"postalCode": "",
"buildingType": 1,
"grossFloorArea": 123456,
"buildingFootprintArea": 123456,
"areaUnits": "",
"floors": 1,
"listed": false,
"buildingTotalHeight": 1,
"averageFloorHeight": 1,
"heightUnits": "",
"wallType": 1,
"frameType": 1,
"sprinklerCoverage": 12,
"reportingCurrency": "",
"buildingQuality" ""
}
Response
| Parameter | Field | Type | Details |
| localTotalCurrencyProfessional | Local Total Currency Professional Fees (LTCP) | Numeric |
The total amount of professional fees it costs to rebuild the structure, in local currency. |
| localDemolitionDebrisRemoval | Local Demolition Debris Removal Fees (LDDRF) | Numeric |
The total amount demolition and debris fees it costs to rebuild the structure, in local currency. |
| localTotalReplacementCost | Local Total Replacement Cost (LTRC) | Numeric |
The total amount it costs to rebuild the structure, in local currency. |
| localReplacementCostPerUnit | Local Replacement Cost Per Unit (LRCPU) | Numeric |
The total amount it costs to rebuild a unit, in local currency. |
| reportingTotalCurrentProfessional | Reporting Total Current Professional Fees (RTCP) | Numeric |
The total amount of professional fees it costs to rebuild the structure, in reporting currency. |
| reportingDemolitionDebrisRemoval | Reporting Demolition and Debris Removal (RDDRF) | Numeric |
The total amount demolition and debris fees it costs to rebuild the structure, in reporting currency. |
| reportingTotalReplacementCost | Reporting Total Replacement Cost (RTRC) | Numeric |
The total amount it costs to rebuild the structure, in reporting currency. |
| reportingReplacementCostPerUnit | Reporting Replacement Cost Per Unit (RRCPU) | Numeric |
The replacement cost per unit area (square foot or square meter). |
| reportingCurrency | Reporting Currency | ISO Currency Code |
The Reporting Currency is applied to the Declared Value on all reports. If no reportingCurrency is provided in the request, then the localCurrency will be used as the reporting currency. The Reporting Currency uses a 3-digit ISO 4217 currency code. |
| areaUnits | Area Units | Square meters or square feet |
The unit of measurement used for Gross Floor Area and Footprint Area. Area Unit values are square feet or square meters. If left blank the system will default to square meters. |
| valueAdequacy | Value Adequacy | String |
The Value Adequacy returns a string indicating the building current risk value according to the information entered in the parameters (Over Insured, Low Risk, Medium Risk, or High Risk). If >= 15% (0.15) value adequacy = High Risk If >= 10% (0.10) and <15% (0.15) value adequacy = Medium Risk If >= 0% (0.00) value adequacy = Low Risk If < 0% (0.00) value adequacy = Over Insured |
Response Structure
{
"localTotalCurrentProfessional": 12345,
"localDemolitionDebrisRemoval": 12345,
"localTotalReplacementCost": 12345,
"localReplacementCostPerUnit": 12345,
"reportingTotalCurrentProfessional": 12345,
"reportingDemolitionDebrisRemoval": 12345,
"reportingTotalReplacementCost": 12345,
"reportingReplacementCostPerUnit": 12345,
"reportingCurrency": "",
"areaUnit": "",
"valueAdequacy": ""
}
- Curl Example Request:
curl -X POST {{baseURL}}/building/riskbenchmark \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"declaredValue": 123456,
"localCurrency": "GBP",
"country": "GB",
"postalCode": "T14ad2",
"buildingType": 1,
"grossFloorArea": 123456,
"buildingFootprintArea": 123456,
"areaUnits": "square feet",
"floors": 1,
"listed": false,
"buildingTotalHeight": "1000",
"averageFloorHeight": "10",
"heightUnits": "feet",
"wallType": 1,
"frameType": 1,
"region": 1,
"sprinklerCoverage": 12,
"reportingCurrency": "USD",
"buildingQuality": "AVG"
}'
Response
{
"localTotalCurrentProfessional": 7424144,
"localDemolitionDebrisRemoval": 6618910,
"localTotalReplacementCost": 108598910,
"localReplacementCostPerUnit": 880,
"reportingTotalCurrentProfessional": 9434152,
"reportingDemolitionDebrisRemoval": 8410909,
"reportingTotalReplacementCost": 138000909,
"reportingReplacementCostPerUnit": 1118,
"reportingCurrency": "USD",
"areaUnits": "square feet",
"valueAdequacy": "High Risk"
}