QuoteEngine.API
Public documentation for BlackFin's 'Quote Engine' API for calculating insurance premiums in New Zealand.
- Introduction
- Authentication
- Quote Setup
- Calculation
- Supported Providers
- Supported Benefits
- Version History
Introduction
Developed by BlackFin Technology Pte Ltd in partnership with the New Zealand Financial Services Group (NZFSG), the 'Quote Engine' API provides efficient and accurate premium calculation/comparison for personal risk and health insurance products from seven of New Zealand’s insurance providers.
API Reference
The Quote Engine API is a RESTful web service where requests are made over HTTPS using the GET and POST methods. Payloads use JSON format object schemas. The API is comprised of three endpoints:
- Quote Setup
GETProviders – returns a list of the insurance providers supported by the Quote Engine, along with the benefits and products that they offer. The object IDs used in this data-set are essential for making a quote calculation request.GETQuoteConfig – returns a list of input parameters and accepted option values for each of the benefits supported by the Quote Engine. This config data may be useful for rendering interfaces for data capture during the quote setup stage.
- Calculation
POSTQuote – the main calculation endpoint, this returns a set of calculated insurance premiums based on the details of the clients, their chosen benefits, and the providers and products that were included in the request.
API Key
The Quote Engine uses an API Key to authenticate all requests. This key is unique to you as a customer and will be provided to you directly by BlackFin. See Authentication for more details.
Environments
The Quote Engine API is provisioned in two environments with the following base URLs:
Hosted on Firebase - Google Cloud Platform - each endpoint is referenced by its unique function name which is passed as a path after the base URL.
Pricing Updates
BlackFin maintains the Quote Engine with the latest rates and calculation updates from the insurers whose premiums are calculated by the API*. Where sufficient notice of these updates has been provided in advance by the insurer, BlackFin will publish these changes in accordance with the insurer's own launch date.
* AIA and Fidelity are exempt from this because the Quote Engine integrates with their own calculation APIs, ensuring that rate updates happen automatically.
See Version History for a list of updates.
Authentication
All requests to the Quote Engine are authenticated via an API key. If a request does not contain a valid key, the Quote Engine will return a 403 error. Requests must be sent over HTTPs.
Request Headers
Your userToken API key should be included in the header of all requests:
| Key | Value |
userToken |
{apiKey} |
Environments
Your userToken API key is the same for both the TEST and PROD environments.
Quote Setup
API specifications for the two Quote Setup endpoints which can be optionally used to assist with the configuration of quotes and/or integration of the API.
Quote Setup
Providers
Returns a list of the insurance providers supported by the API, along with the benefits and products that they offer. This data will only change a few times per year, depending on any renaming or addition/removal of products by the insurers.
Request
- Type:
GET - Path:
/providers
Authentication
A userToken API key is required to authenticate the request source. This should be included in the header of the request.See Authentication for more details.
Response
Success
200: Success
JSON Schema
{
"type": "object",
"properties": {
"providerId": {
"type": "integer",
"description": "The API's internal ID for the current provider. <br /><br />\r\nThis ID is used within the payload of the request of the `/quote` endpoint when requesting the calculation of a premium from this provider.",
"format": "int32"
},
"providerName": {
"type": "string",
"description": "The display name of the current provider",
"nullable": true
},
"hexColor": {
"type": "string",
"description": "A hex color value representing the dominant colour from the provider's logo that can be incorporated into the design of the UI if desired.",
"nullable": true
},
"logoUrl": {
"type": "string",
"description": "The URL of the provider's logo image (hosted by BlackFin) that can be displayed with the UI if desired.",
"nullable": true
},
"benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"benefitId": {
"type": "integer",
"description": "The API's internal ID for the current benefit. <br /><br />\r\nThis ID is used within the payload of the request of the `/quote` endpoint when requesting the calculation of a premium for this benefit.",
"format": "int32"
},
"benefitName": {
"type": "string",
"description": "The display name of the current benefit",
"nullable": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"description": "The API's internal ID for the current product. <br /><br />\r\nThis ID is used within the payload of the request of the '/quote' endpoint when requesting the calculation of a premium for this product.\"",
"format": "int32"
},
"productName": {
"type": "string",
"description": "The display name of the current product",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of one or more objects detailing the product(s) which the current provider offers under this benefit.",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of benefit objects detailing which benefits the current provider offers.",
"nullable": true
}
},
"additionalProperties": false
}Examples
Success Response
{
"providerId": 0,
"providerName": "string",
"hexColor": "string",
"logoUrl": "string",
"benefits": [
{
"benefitId": 0,
"benefitName": "string",
"products": [
{
"productId": 0,
"productName": "string"
}
]
}
]
}Error
403: userToken is invalid or no longer valid
Quote Setup
QuoteConfig
Returns a list of input parameters that are used when configuring the different benefits within the /quote calculation request. The returned input parameters are defined by their type (eg. dropdown list) and their accepted option values, and are grouped by the benefits they are relevant for. This data could be used to render UI elements for data capture during the configuration of a quote.
Request
- Type:
GET - Path:
/quoteConfig
Authentication
A userToken API key is required to authenticate the request source. This should be included in the header of the request. See Authentication for more details.
Response
Success
200: Success
JSON Schema
{
"type": "object",
"properties": {
"quoteConfig": {
"type": "object",
"properties": {
"benefits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"benefitId": {
"type": "integer",
"description": "The API's internal ID for the current benefit. <br /><br />\r\nThis ID is used within the payload of the request of the `/quote` endpoint when requesting the calculation of a premium for this benefit.",
"format": "int32"
},
"benefitName": {
"type": "string",
"description": "The display name of the current benefit",
"nullable": true
},
"inputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"inputId": {
"type": "string",
"description": "The underlying name of the input. Each of these values matches to an equivalent property in the payload schema of the `/quote` request.\r\nFor example \"calcPeriod\" or \"coverAmount\"",
"nullable": true
},
"inputLabel": {
"type": "string",
"description": "The human-friendly name of the input. This can be displayed as the field label in the UI.",
"nullable": true
},
"inputType": {
"type": "string",
"description": "Defines the type of field that could be used to capture the input. The possible values are: <br /><br />\r\n`checkbox` – a true/false boolean input <br />\r\n`currency` – a number representing a monetary value in NZD <br />\r\n`dropdown` – an input with pre-defined set of options(see below) <br />\r\n`number` – a quantity of something(non-currency)",
"nullable": true
},
"inputOptions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The human-friendly name of the option which can be displayed in the dropdown in the UI.",
"nullable": true
},
"value": {
"type": "string",
"description": "The underlying value of the option. This value (for the chosen option) should be included in the `/quote` request payload",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of pre-defined values for `dropdown` type inputs",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of objects detailing the data capture inputs that are relevant for the current benefit. \r\nThe list of inputs varies for each type of benefit, although there is some crossover between most benefits.",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of insurance benefits which are supported for quoting via the Quote Engine API.",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Examples
Success Response
{
"quoteConfig": {
"benefits": [
{
"benefitId": 0,
"benefitName": "string",
"inputs": [
{
"inputId": "string",
"inputLabel": "string",
"inputType": "string",
"inputOptions": [
{
"name": "string",
"value": "string"
}
]
}
]
}
]
}
}Error
403: userToken is invalid or no longer valid
Calculation
API specification for the Quote calculation endpoint
Calculation
Quote Request
The Quote endpoint returns a list of quote results containing premiums that have been calculated based on details provided in the request. These details must include client demographics, chosen benefit options, and the providers and products they are interested in.
Each request generates a new quote. Whilst the Quote Engine does log all requests for analytics and troubleshooting purposes, quotes are not saved by the API and it does not provide methods to retrieve, modify, or delete previous quotes.
Request
- Type:
POST - Path:
/quote
Authentication
A userToken API key is required to authenticate the request source. This should be included in the header of the request. See Authentication for more details.
Payload Structure
The data in the Quote request payload is structured as follows:
- Clients – A quote must contain one or more
clientobjects, detailing the persons to be insured. - ClientBenefits – Each client must contain at least one
clientBenefitobject which details the benefit (type of insurance) that is being requested for that client. The required properties for this object vary depending on the type of benefit. See JSON Schema below for more details. Benefit types are defined using abenefitId. - BenefitProducts – Under each client benefit is a
benefitProductsarray that defines which providers (insurers) and products to be quoted. These are defined as a pair ofproviderIdandproductIdkeys. Supported products can be queried from the /providers endpoint. - ClientProviderSettings – This is an optional array of provider-specific settings for each client - for example, whether the client is eligible for Chubb's 'Lifetime Reward' discount.
- Settings – Each request must contain a
settingsobject that defines the settings for the quote, such as thepaymentFrequency. - ProviderSettings – This is an optional array of provider-specific settings that should be applied to the whole quote - for example, whether all clients wish to join AIA's 'Vitality' programme.
JSON Schema
The request payload is sent as HTTP JSON body using the following schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$defs": {
"Benefit.benefitId": {
"type": "integer",
"description": "The id of the benefit to be quoted. See [supported benefits](https://docs.blackfin.tools/books/quoteengineapi/page/supported-benefits)",
"format": "int32"
},
"Benefit.clientBenefitId": {
"type": "string",
"description": "Optional custom identifier provided by the requestor. This is returned with the result in the response.",
"nullable": true
},
"Benefit.loading": {
"type": "number",
"description": "Optional loading multiplier for the current benefit, for example: <br /><br /> \r\n `1.0` – no additional loading <br /> \r\n `1.5` – 50% additional loading <br /> \r\n `2.0` – 100% additional loading",
"format": "double",
"default": 1
},
"Benefit.indexed": {
"type": "boolean",
"description": "Toggle CPI Indexation on and off for the current benefit: <br /><br /> \r\n `false` – no indexation <br /> \r\n `true` – apply CPI indexation",
"default": true
},
"Benefit.benefitProducts": {
"type": "array",
"items": {
"required": [
"productId",
"providerId"
],
"type": "object",
"properties": {
"providerId": {
"type": "integer",
"description": "The id of the provider whose product is being quoted.",
"format": "int32"
},
"productId": {
"type": "integer",
"description": "The id of the product being quoted.",
"format": "int32"
}
},
"additionalProperties": false
},
"description": "An array of one or more Product objects containing the details of the providers and products to be quoted for the current beneft."
}
},
"required": [
"clients",
"settings"
],
"type": "object",
"properties": {
"clients": {
"type": "array",
"items": {
"required": [
"age",
"clientBenefits",
"employedStatus",
"gender",
"occupationId",
"smoker"
],
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "First name of the individual to be insured",
"nullable": true
},
"lastName": {
"type": "string",
"description": "Last name of the indivual to be insured",
"nullable": true
},
"age": {
"type": "integer",
"description": "Current age of the individual to be insured",
"format": "int32"
},
"gender": {
"type": "string",
"description": "Gender of the individual to be insured: <br /><br />\r\n`F` – Female <br />\r\n`M` – Male"
},
"smoker": {
"type": "boolean",
"description": "Indicates whether the individual to be insured is a smoker: <br /><br />\r\n`false` – Non-smoker <br />\r\n`true` – Smoker <br />"
},
"employedStatus": {
"type": "string",
"description": "The employment status of the individual to be insured: <br /><br />\r\n `Employed` <br />\r\n `Self-employed` <br />\r\n `Self-employed < 3 Years` <br />\r\n `Non-earner` <br /><br />\r\n This property is not required when quoting for Health Cover, Life Cover, Family Protection, and Trauma Cover",
"default": "Employed"
},
"occupationId": {
"type": "integer",
"description": "The occupation class of the individual to be insured: <br /><br />\r\n`1` – Class 1 <br />\r\n`2` – Class 2 <br />\r\n`3` – Class 3 <br />\r\n`4` – Class 4 <br />\r\n`5` – Class 5 <br /><br />\r\nThis property is not required when quoting for Health Cover, Life Cover, Family Protection, or Trauma Cover.",
"format": "int32"
},
"isChild": {
"type": "boolean",
"description": "Inidicates whether the individual to be insured is a child / dependent: <br /><br />\r\n `false` – adult <br />\r\n `true` – child / dependent",
"default": false
},
"clientId": {
"type": "string",
"description": "Optional custom identifier provided by the requestor. This is returned with the result in the response.",
"nullable": true
},
"clientBenefits": {
"type": "array",
"items": {
"anyOf": [
{
"title": "1 – Health Cover",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"excess": {
"type": "integer",
"description": "Defines the excess amount (in NZD) payable by the client under Health Cover, for example: <br /><br />\r\n`0` – nil excess <br />\r\n`250` – $250 excess <br />\r\n`500` – $500 excess etc",
"format": "int32",
"default": 0,
"nullable": true
},
"gpPrescriptions": {
"type": "boolean",
"description": "Toggle the optional GP & Prescriptions benefit (under Health Cover) on and off : <br /><br />\r\n`false` – not included <br />\r\n`true` – include GP & Prescriptions",
"default": false,
"nullable": true
},
"specialistsTest": {
"type": "boolean",
"description": "Toggle the optional Specialists & Tests benefit (under Health Cover) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Specialists & Tests",
"default": false,
"nullable": true
},
"specialistsTestExcess": {
"type": "integer",
"description": "Defines the excess amount (in NZD) payable by the client under the Specialists & Tests benefit, if applicable. For example: <br /><br />\r\n`0` – nil excess <br />\r\n`250` – $250 excess <br /><br />\r\nIf not provided, the primary `Excess` value will be used.",
"format": "int32",
"nullable": true
},
"dentalOptical": {
"type": "boolean",
"description": "Toggle the optional Dental & Optical benefit (under Health Cover) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Dental & Optical",
"default": false,
"nullable": true
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "2 – Life Cover",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"calcPeriod",
"coverAmount"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"calcPeriod": {
"type": "number",
"description": "The premium review term for the benefit: <br /><br />\r\n `1` – Yearly Renewable (Stepped) <br />\r\n `5`, `10`, `15` – Level for specified number of years <br />\r\n `50`, `60`, `65`, `70` etc – Level to specified age",
"format": "double",
"default": 1
},
"futureInsurability": {
"type": "boolean",
"description": "Toggle the optional Future Insurability benefit (under Life Cover) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Future Insurability",
"default": false,
"nullable": true
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "3 – Family Protection (Life Income)",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"benefitPeriod",
"benefitPeriodType",
"coverAmount"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"benefitPeriod": {
"type": "integer",
"description": "Specifies the period of time for which the benefit will be payable – either as a specific number of years (eg. '5' years) or to a specific age (eg. age '65'). <br /><br /> See `benefitPeriodType` for definition.",
"format": "int32"
},
"benefitPeriodType": {
"type": "string",
"description": "Defines whether the `benefitPeriod` number is expressed as: <br /><br />\r\n`age` – to a specific age <br />\r\n`term` – a fixed term (specific number of years) <br />"
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "4 – Trauma Cover",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"calcPeriod",
"coverAmount"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"calcPeriod": {
"type": "number",
"description": "The premium review term for the benefit: <br /><br />\r\n `1` – Yearly Renewable (Stepped) <br />\r\n `5`, `10`, `15` – Level for specified number of years <br />\r\n `50`, `60`, `65`, `70` etc – Level to specified age",
"format": "double",
"default": 1
},
"accelerated": {
"type": "boolean",
"description": "Toggle acceleration on and off for Trauma Cover: <br /><br />\r\n `false` – standalone <br />\r\n `true` – accelerated <br /><br />\r\n Quote must also include a Life Cover benefit for the same client, in order to accelerate the Trauma Cover",
"default": false,
"nullable": true
},
"traumaBuyback": {
"type": "boolean",
"description": "Toggle the optional Trauma BuyBack benefit (under Trauma) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Trauma BuyBack",
"default": false,
"nullable": true
},
"traumaBuybackType": {
"type": "string",
"description": "Defines the type of Trauma Buyback benefit to be quoted. Not all providers offer both options: <br /><br />\r\n `deferred` – cover continues after a stand-down period (usually 12 months) following a claim <br />\r\n`instant` – cover continues immediately following a claim <br /><br />\r\n This setting is ignored unless `traumaBuyback = true`",
"default": "deferred",
"nullable": true
},
"lifeBuyback": {
"type": "boolean",
"description": "Toggle the optional Life BuyBack benefit (under Accelerated Trauma) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Life BuyBack <br /> <br />\r\n Only applicable if `accelerated = true`",
"default": false,
"nullable": true
},
"tpdAddon": {
"type": "boolean",
"description": "<br /> Toggle the optional TPD Add-On benefit (under Trauma) on and off : <br /><br />\r\n `false` – not included(default value) <br />\r\n `true` – include TPD Add-On <br /><br />\r\n The `occupationType` property is required if including the TPD Add-On (see below)",
"default": false,
"nullable": true
},
"occupationType": {
"type": "string",
"description": "Defines whether the TPD Add-On benefit covers the individual's inability to work in their current (own) occupation: <br /><br />\r\n`own` – own occupation <br />\r\n`any` – any occupation <br /><br />\r\n This setting is only required if `tpdAddon = true`",
"nullable": true
},
"seriousTrauma": {
"type": "boolean",
"description": "Toggle the optional Serious Trauma benefit (under Trauma) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Serious Trauma <br /><br />\r\n The `seriousTraumaCoverAmount` is required if including the Serious Trauma benefit (see below)",
"default": false,
"nullable": true
},
"seriousTraumaCoverAmount": {
"type": "number",
"description": "Amount of cover (in New Zealand Dollars) for the optional Serious Trauma benefit. <br />\r\nOnly required if `seriousTrauma = true`",
"format": "double",
"nullable": true
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "5 – Total & Permanent Disability",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"calcPeriod",
"coverAmount",
"occupationType"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"calcPeriod": {
"type": "number",
"description": "The premium review term for the benefit: <br /><br />\r\n `1` – Yearly Renewable <br />\r\n `5`, `10`, `15` – Level for specified number of years <br />\r\n `50`, `60`, `65`, `70` etc – Level to specified age",
"format": "double",
"default": 1
},
"accelerated": {
"type": "boolean",
"description": "Toggle acceleration on and off for TPD: <br /><br />\r\n `false` – standalone <br />\r\n `true` – accelerated <br /><br />\r\n Quote must also include a Life Cover benefit for the same client, in order to accelerate the TPD",
"default": false,
"nullable": true
},
"occupationType": {
"type": "string",
"description": "Defines whether the TPD benefit covers the individual's inability to work in their current (own) occupation: <br /><br />\r\n`own` – own occupation <br />\r\n`any` – any occupation <br />",
"nullable": true
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "6 – Income Protection",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"benefitPeriod",
"benefitPeriodType",
"coverAmount",
"weekWaitPeriod"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"benefitPeriod": {
"type": "integer",
"description": "Specifies the period of time for which the benefit will be payable – either as a specific number of years (eg. '5' years) or to a specific age (eg. age '65'). <br /><br /> See `benefitPeriodType` for definition.",
"format": "int32"
},
"benefitPeriodType": {
"type": "string",
"description": "Defines whether the `benefitPeriod` number is expressed as: <br /><br />\r\n`age` – to a specific age <br />\r\n`term` – a fixed term (specific number of years) <br />"
},
"weekWaitPeriod": {
"type": "number",
"description": "Specifies the number of weeks after which the benefit will start to be paid",
"format": "double"
},
"booster": {
"type": "boolean",
"description": "Toggle the optional Booster benefit (under Income Protection) on and off : <br /><br />\r\n `false` – not included <br />\r\n `true` – include Booster <br />",
"default": false,
"nullable": true
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "7 – Mortgage Repayment Cover",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"benefitPeriod",
"benefitPeriodType",
"coverAmount",
"weekWaitPeriod"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"benefitPeriod": {
"type": "integer",
"description": "Specifies the period of time for which the benefit will be payable – either as a specific number of years (eg. '5' years) or to a specific age (eg. age '65'). <br /><br /> See `benefitPeriodType` for definition.",
"format": "int32"
},
"benefitPeriodType": {
"type": "string",
"description": "Defines whether the `benefitPeriod` number is expressed as: <br /><br />\r\n`age` – to a specific age <br />\r\n`term` – a fixed term (specific number of years) <br />"
},
"weekWaitPeriod": {
"type": "number",
"description": "Specifies the number of weeks after which the benefit will start to be paid",
"format": "double"
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "8 – Redundancy Cover",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"coverAmount"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"indexed": {
"$ref": "#/$defs/Benefit.indexed"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "9 – Waiver of Premium",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"weekWaitPeriod"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"weekWaitPeriod": {
"type": "number",
"description": "Specifies the number of weeks after which the benefit will start to be paid",
"format": "double",
"nullable": true
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
},
{
"title": "10 – Special Injury",
"type": "object",
"description": "An array of one or more Benefit objects containing the details of the insurance benefit(s) to be quoted for the current client. Not all properties are relevant for every benefit. <br /><br />\r\nSelect each `benefitId` from the dropdown above to see the relevant properties.",
"required": [
"benefitId",
"benefitProducts",
"coverAmount"
],
"properties": {
"benefitId": {
"$ref": "#/$defs/Benefit.benefitId"
},
"clientBenefitId": {
"$ref": "#/$defs/Benefit.clientBenefitId"
},
"coverAmount": {
"type": "number",
"description": "Amount of cover / sum insured, in New Zealand Dollars (NZD). Value is treated as: <br />\r\n* <b>Lump Sum</b> amount for Life, Trauma, TPD <br />\r\n* <b>Annual</b> cover for Income Protection <br />\r\n* <b>Monthly</b> amount/cover for Family Protection, Mortgage, Redundancy, Special Injury",
"format": "double"
},
"loading": {
"$ref": "#/$defs/Benefit.loading"
},
"benefitProducts": {
"$ref": "#/$defs/Benefit.benefitProducts"
}
}
}
]
}
},
"clientProviderSettings": {
"type": "array",
"description": "Optional array of provider-specific settings to be applied to the current client.",
"nullable": true,
"items": {
"required": [
"providerId"
],
"type": "object",
"properties": {
"providerId": {
"type": "integer",
"description": "The id of the provider for which settings are being applied. <br /><br />\r\nNote: at the current time, only the provider Chubb Life (id=8) has any applicable settings here.",
"format": "int32"
},
"lifetimeRewardSelected": {
"type": "boolean",
"description": "Toggle the Chubb Life 'Lifetime Reward' discount on and off for the current client. Eligible clients receive a lifetime discount on certain benefits: <br /><br />\r\n`false` – client not eligible for Lifetime Reward <br />\r\n`true` – client is eligible for Lifetime Reward",
"default": false,
"nullable": true
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"description": "An array of Client objects containing the details of the individuals to be insured"
},
"settings": {
"required": [
"paymentFrequency"
],
"type": "object",
"properties": {
"paymentFrequency": {
"type": "integer",
"description": "The desired frequency for premium payments: <br /><br />\r\n`1` – Annually <br />\r\n`12` – Monthly <br />\r\n`26` – Fortnightly",
"format": "int32"
},
"calcDate": {
"type": "string",
"description": "Optional parameter that can be used to request calculation of premiums for a certain date (eg. historical or upcoming) where possible. Note: this is not supported for all providers so should not be heavily relied upon.",
"format": "YYYY-MM-DD",
"default": "{currentDate}",
"nullable": true
},
"providerSettings": {
"type": "array",
"items": {
"required": [
"providerId"
],
"type": "object",
"properties": {
"providerId": {
"type": "integer",
"description": "The id of the provider for which settings are being applied. <br /><br />\r\nNote: at the current time, only the provider AIA (id=11) has any applicable settings here.",
"format": "int32"
},
"vitalityDiscountSelected": {
"type": "boolean",
"description": "Toggle the AIA Vitality scheme membership on and off for all clients. Members of AIA's Vitality scheme receive a discount on their insurance premium: <br /><br />\r\n`false` – clients do not wish to join AIA Vitality <br />\r\n`true` – clients wish to join (or are already members of) AIA Vitality <br /><br />\r\n See related `vitalityFeeSelected` property below",
"default": false,
"nullable": true
},
"vitalityFeeSelected": {
"type": "boolean",
"description": "Toggle the applicability of the AIA Vitality fee, based on whether the client(s) are already members of the scheme: <br /><br />\r\n`false` – clients are already paying AIA Vitality fee(existing members) <br />\r\n`true` – clients are not existing Vitality members, therefore the fee is applicable",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An optional array of provider-specific settings. <br /><br />\r\nNot all providers have applicable settings(see below) however this may change in future.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Quote Settings object. The settings entered here will be defined to the overall quote (ie. all clients and benefits)"
},
"comboQuoteId": {
"type": "string",
"nullable": true,
"description": "Optional user-provided ID to indicate that the request is one of multiple requests sent to calculate a 'Combo Quote', allowing BlackFin to group these requests together for analytics purposes."
}
},
"additionalProperties": false
}Examples
Example request payload:
JSON Request Body
{
"clients": [
{
"firstName": "John",
"lastName": "Smith",
"age": 35,
"gender": "M",
"smoker": false,
"employedStatus": "Employed",
"occupationId": 2,
"isChild": false,
"clientId": "YourClientId1",
"clientBenefits": [
{
"benefitId": 1,
"clientBenefitId": "YourClientId1.Health",
"excess": 250,
"gpPrescriptions": false,
"specialistsTest": true,
"specialistsTestExcess": 250,
"dentalOptical": false,
"loading": 1,
"benefitProducts": [
{
"providerId": 1,
"productId": 105
},
{
"providerId": 7,
"productId": 12
},
{
"providerId": 9,
"productId": 10
},
{
"providerId": 11,
"productId": 11
}
]
},
{
"benefitId": 2,
"clientBenefitId": "YourClientId1.Life",
"coverAmount": 500000,
"calcPeriod": 1,
"futureInsurability": false,
"indexed": true,
"loading": 1,
"benefitProducts": [
{
"providerId": 5,
"productId": 6
},
{
"providerId": 6,
"productId": 7
},
{
"providerId": 8,
"productId": 3
},
{
"providerId": 9,
"productId": 2
},
{
"providerId": 11,
"productId": 4
}
]
}
],
"clientProviderSettings": [
{
"providerId": 8,
"lifetimeRewardSelected": true
}
]
},
{
"firstName": "Jane",
"lastName": "Smith",
"age": 30,
"gender": "F",
"smoker": true,
"employedStatus": "Self-employed",
"occupationId": 1,
"isChild": false,
"clientId": "YourClientId2",
"clientBenefits": [
{
"benefitId": 4,
"clientBenefitId": "YourClientId2.Trauma",
"coverAmount": 350000,
"calcPeriod": 65,
"accelerated": false,
"traumaBuyback": true,
"traumaBuybackType": "deferred",
"lifeBuyback": false,
"tpdAddon": false,
"occupationType": null,
"seriousTrauma": false,
"seriousTraumaCoverAmount": null,
"indexed": true,
"loading": 1,
"benefitProducts": [
{
"providerId": 5,
"productId": 26
},
{
"providerId": 6,
"productId": 28
},
{
"providerId": 8,
"productId": 22
},
{
"providerId": 9,
"productId": 21
},
{
"providerId": 11,
"productId": 24
}
]
},
{
"benefitId": 6,
"clientBenefitId": "YourClientId2.Income",
"coverAmount": 75000,
"benefitPeriod": 65,
"benefitPeriodType": "age",
"weekWaitPeriod": 4,
"booster": false,
"indexed": true,
"loading": 1,
"benefitProducts": [
{
"providerId": 5,
"productId": 108
},
{
"providerId": 6,
"productId": 69
},
{
"providerId": 8,
"productId": 58
},
{
"providerId": 9,
"productId": 49
},
{
"providerId": 11,
"productId": 46
}
]
}
],
"clientProviderSettings": null
}
],
"settings": {
"paymentFrequency": 12,
"calcDate": null,
"providerSettings": [
{
"providerId": 11,
"vitalityDiscountSelected": true,
"vitalityFeeSelected": true
}
]
},
"comboQuoteId": null
}
Response
See Quote Results for a detailed explanation of this endpoint's response.
Response Codes
200: Success
400: Request body is null or invalid
403: userToken is invalid or no longer valid
Calculation
Quote Results
This page details the response from the /quote calculation endpoint. See Quote Request for details about how to make a request to this endpoint.
Response
Success
200: Success
Payload Structure
The data in the Quote response payload is structured as follows:
- Results – A successful response will contain one or more
resultobjects. Each result relates to a specific provider (insurer) as defined by itsproviderId. This object contains the overalltotalPremiumfor that provider, along with any applicable fees. - Clients – Each result is split out by the
clientobject(s) contained within it, as provided during the request. - Products – Under each client is an array of
productobjects, based on thebenefitIdandproductIdvalues included in the request. This contains the itemisedpremiumthat has been calculated for that product. - Descriptions – This is an array of description strings that summarises the key attributes of the product that was calculated – for example, the cover amount, any optional add-ons that were included, and any discounts that were applied.
- Errors – Any products which were unable to be calculated will contain one or more
errorsdetailing the reason for failure – for example, where an optional add-on or requested setting is not supported by the provider.
JSON Schema
The response payload is received as HTTP JSON body using the following schema:
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"providerId": {
"type": "integer",
"description": "The ID of the provider for the current result.",
"format": "int32"
},
"providerName": {
"type": "string",
"description": "The name of the provider for the current result.",
"nullable": true
},
"providerLogoUrl": {
"type": "string",
"description": "The URL of the provider's logo image (hosted by BlackFin) that can be displayed with the result if desired.",
"nullable": true
},
"hexColor": {
"type": "string",
"description": "A hex color value representing the dominant colour from the provider's logo that can be incorporated into the design of the displayed result if desired.",
"nullable": true
},
"hasErrors": {
"type": "boolean",
"description": "Identifies whether the result is fully formed or whether there are errors within some products in the result. <br /><br />\r\n`false` – premiums have been successfully calculated for all products <br />\r\n`true` – at least one product contain errors <br /><br />\r\nIf `true` there will be at least one `error` message included within the products below."
},
"policyFee": {
"type": "number",
"description": "The amount of the applicable Policy Fee in New Zealand Dollars [NZD]",
"format": "double"
},
"vitalityFee": {
"type": "number",
"description": "The amount of the Vitality Fee (AIA only) in New Zealand Dollars [NZD], if applicable.",
"format": "double",
"nullable": true
},
"totalPremium": {
"type": "number",
"description": "The sum total of all individual product premiums (for all clients) in the current result - plus any applicable fees - in New Zealand Dollars [NZD].",
"format": "double"
},
"clients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"description": "Returns the optional 'clientId' from the request, if one was provided by the requestor.",
"nullable": true
},
"clientName": {
"type": "string",
"description": "The fullname of the client for whom products have been quoted in the result. <br /><br />\r\nIf no `firstName` and/or `lastName` were provided by the requestor, the API will return an auto-generated name like \"Client 1\"",
"nullable": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientBenefitId": {
"type": "string",
"description": "Returns the optional 'clientBenefitId' from the request, if one was provided by the requestor.",
"nullable": true
},
"benefitId": {
"type": "integer",
"description": "The ID of the benefit that has been quoted.",
"format": "int32"
},
"productId": {
"type": "integer",
"description": "The ID of the product that has been quoted.",
"format": "int32"
},
"productName": {
"type": "string",
"description": "The display name of the product that has been quoted.",
"nullable": true
},
"descriptions": {
"type": "array",
"items": {
"type": "string"
},
"description": "An optional array of strings containing additional descriptions about this product result – for example, any discounts that have been applied.",
"nullable": true
},
"premium": {
"type": "number",
"description": "The calculated premium amount for the current product (under the current client) in New Zealand Dollars [NZD].",
"format": "double"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Internal ID reference (from BlackFin) for the current error.",
"format": "int32"
},
"message": {
"type": "string",
"description": "The description of the error that was encountered. This is a human-friendly message that can be displayed to the user. For example: <br /><br /><i>\"TPD Add-on is not available for your occupation class\"</i>",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of one or more objects detailing any errors encountered whilst failing to calculate a premium for the current product.",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of one or more product objects that have been quoted for the current client in the result.",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of one or more client objects for whom products have been quoted in the current result.",
"nullable": true
}
},
"additionalProperties": false
},
"description": "An array of quote result objects – one for every provider quoted. Each object contains the details needed to render the provider's result in a UI.",
"nullable": true
},
"quoteId": {
"type": "string",
"description": "The ID of the current quote, auto-generated by the API"
},
"paymentFrequency": {
"type": "string",
"description": "The display name of the chosen payment frequency. The possible values are:\r\n\r\n`Yearly` <br />\r\n`Monthly` <br />\r\n`Fortnightly`",
"nullable": true
},
"calcTime": {
"type": "number",
"description": "The amount of time taken by the API (in seconds) to calculate all premiums in the results.",
"format": "double"
},
"apiVersion": {
"type": "string",
"description": "API version / last update information",
"nullable": true
}
},
"additionalProperties": false
}Examples
Success Response
{
"results": [
{
"providerId": 9,
"providerName": "Partners Life",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/9.png",
"hexColor": "#004855",
"hasErrors": true,
"policyFee": 0,
"vitalityFee": null,
"totalPremium": 0,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Health",
"benefitId": 1,
"productId": 10,
"productName": "Private Medical",
"descriptions": [
"Specialist & Tests"
],
"premium": 0,
"errors": []
},
{
"clientBenefitId": "YourClientId1.Life",
"benefitId": 2,
"productId": 2,
"productName": "Life Cover",
"descriptions": [],
"premium": 0,
"errors": []
}
]
},
{
"clientId": "YourClientId2",
"clientName": "Jane Smith",
"products": [
{
"clientBenefitId": "YourClientId2.Trauma",
"benefitId": 4,
"productId": 21,
"productName": "Level Trauma Cover",
"descriptions": [
"$350,000, Level to Age 65",
"Standalone",
"Trauma Buyback (Deferred)"
],
"premium": 0,
"errors": []
},
{
"clientBenefitId": "YourClientId2.Income",
"benefitId": 6,
"productId": 49,
"productName": "Agreed Value",
"descriptions": null,
"premium": 0,
"errors": [
{
"id": 6032,
"message": "Agreed Value is not available for Self-Employed"
}
]
}
]
}
]
},
{
"providerId": 1,
"providerName": "Accuro",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/1.png",
"hexColor": "#00aeef",
"hasErrors": false,
"policyFee": 0.00,
"vitalityFee": null,
"totalPremium": 115.87,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Health",
"benefitId": 1,
"productId": 105,
"productName": "SmartCare",
"descriptions": [
"Specialist & Tests"
],
"premium": 115.87,
"errors": []
}
]
}
]
},
{
"providerId": 7,
"providerName": "nib",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/7.png",
"hexColor": "#144b37",
"hasErrors": false,
"policyFee": 6.75,
"vitalityFee": null,
"totalPremium": 139.02,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Health",
"benefitId": 1,
"productId": 12,
"productName": "Ultimate Health Base Cover",
"descriptions": [
"Specialist & Tests"
],
"premium": 132.27,
"errors": []
}
]
}
]
},
{
"providerId": 5,
"providerName": "Asteron",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/5.png",
"hexColor": "#0092da",
"hasErrors": false,
"policyFee": 0.00,
"vitalityFee": null,
"totalPremium": 469.30,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Life",
"benefitId": 2,
"productId": 6,
"productName": "Life Cover",
"descriptions": [],
"premium": 37.63,
"errors": []
}
]
},
{
"clientId": "YourClientId2",
"clientName": "Jane Smith",
"products": [
{
"clientBenefitId": "YourClientId2.Trauma",
"benefitId": 4,
"productId": 26,
"productName": "Level Trauma Cover",
"descriptions": [
"$350,000, Level to Age 65",
"Standalone",
"Trauma Buyback (Deferred)",
"7.5% bundling discount applied"
],
"premium": 236.26,
"errors": []
},
{
"clientBenefitId": "YourClientId2.Income",
"benefitId": 6,
"productId": 108,
"productName": "Agreed Value",
"descriptions": [
"$75,000, To Age 65",
"inclusive Waiver of Premium",
"7.5% bundling discount applied"
],
"premium": 195.41,
"errors": []
}
]
}
]
},
{
"providerId": 8,
"providerName": "Chubb Life",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/8.png",
"hexColor": "#041a71",
"hasErrors": false,
"policyFee": 6.50,
"vitalityFee": null,
"totalPremium": 562.19,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Life",
"benefitId": 2,
"productId": 3,
"productName": "Life Cover",
"descriptions": [
"10% Lifetime Reward applied"
],
"premium": 28.06,
"errors": []
}
]
},
{
"clientId": "YourClientId2",
"clientName": "Jane Smith",
"products": [
{
"clientBenefitId": "YourClientId2.Trauma",
"benefitId": 4,
"productId": 22,
"productName": "Level Trauma",
"descriptions": [
"$350,000, Level to Age 65",
"Standalone",
"Trauma Buyback (Deferred)"
],
"premium": 308.05,
"errors": []
},
{
"clientBenefitId": "YourClientId2.Income",
"benefitId": 6,
"productId": 58,
"productName": "Agreed Value",
"descriptions": [
"$75,000, To Age 65"
],
"premium": 219.58,
"errors": []
}
]
}
]
},
{
"providerId": 6,
"providerName": "Fidelity Life",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/6.png",
"hexColor": "#071e2b",
"hasErrors": false,
"policyFee": 9.75,
"vitalityFee": null,
"totalPremium": 639.74,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Life",
"benefitId": 2,
"productId": 7,
"productName": "Life Cover",
"descriptions": null,
"premium": 31.34,
"errors": []
}
]
},
{
"clientId": "YourClientId2",
"clientName": "Jane Smith",
"products": [
{
"clientBenefitId": "YourClientId2.Trauma",
"benefitId": 4,
"productId": 28,
"productName": "Level Platinum Plus Trauma",
"descriptions": null,
"premium": 394.85,
"errors": []
},
{
"clientBenefitId": "YourClientId2.Income",
"benefitId": 6,
"productId": 69,
"productName": "Agreed Value",
"descriptions": null,
"premium": 203.8,
"errors": []
}
]
}
]
},
{
"providerId": 11,
"providerName": "AIA",
"providerLogoUrl": "https://quote-engine-test.blackfin.tools/Docs/ProviderLogos/2.png",
"hexColor": "#d12047",
"hasErrors": false,
"policyFee": 15.08,
"vitalityFee": 23,
"totalPremium": 774.18,
"clients": [
{
"clientId": "YourClientId1",
"clientName": "John Smith",
"products": [
{
"clientBenefitId": "YourClientId1.Health",
"benefitId": 1,
"productId": 11,
"productName": "Private Health",
"descriptions": [
"Specialist & Tests",
"Vitality Discount applied ($13.06)"
],
"premium": 117.59,
"errors": []
},
{
"clientBenefitId": "YourClientId1.Life",
"benefitId": 2,
"productId": 4,
"productName": "Living Life Cover",
"descriptions": [
"Vitality Discount applied ($3.15)"
],
"premium": 28.39,
"errors": []
}
]
},
{
"clientId": "YourClientId2",
"clientName": "Jane Smith",
"products": [
{
"clientBenefitId": "YourClientId2.Trauma",
"benefitId": 4,
"productId": 24,
"productName": "Living Level Critical Conditions",
"descriptions": [
"$350,000, Level to Age 65",
"Standalone",
"Trauma Buyback",
"Vitality Discount applied ($40.52)"
],
"premium": 364.72,
"errors": []
},
{
"clientBenefitId": "YourClientId2.Income",
"benefitId": 6,
"productId": 46,
"productName": "Living Income Protection Agreed Value",
"descriptions": [
"$75,000, To Age 65",
"Vitality Discount applied ($25.04)"
],
"premium": 225.4,
"errors": []
}
]
}
]
}
],
"quoteId": "UZp2HBlUpuzDf6bECC5o",
"comboQuoteId": null,
"paymentFrequency": "Monthly",
"calcTime": 7.4626,
"apiVersion": "quote-00122-hez"
}Error
400: Request body is null or invalid
JSON Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"response": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Examples
Error Response
{
"data": {
"response": {
"code": 0,
"message": "string"
}
}
}403: userToken is invalid or no longer valid
Supported Providers
The following insurance providers are available to be quoted via the Quote Engine.
This information can be queried via a GET /providers request.
| Provider | Name & ID | Available Benefits | Available Discounts |
|
|
Accuro ProviderId:
|
|
|
|
|
AIA ProviderId: |
|
|
|
|
Asteron Life ProviderId: |
|
|
|
|
Chubb Life ProviderId: |
|
|
|
|
Fidelity Life ProviderId: |
|
|
|
|
nib ProviderId: |
|
|
|
|
Partners Life ProviderId: |
|
|
Premiums for all providers are calculated internally by BlackFin using the insurers' base rates and pricing algorithms, with the exception of AIA and Fidelity – where the Quote Engine acts as middleware between the requestor and the insurers' own quoting APIs.
Supported Benefits
The following insurance benefits are available to be quoted via the Quote Engine:
| ID | Benefit | Description | Optional Add-Ons |
1 |
Health Cover | Helps to cover the cost of the insured person's medical expenses. |
|
2 |
Life Cover | Provides a lump sum payment to the insured person's family (or beneficiaries) in the event of the insured person's death. |
|
3 |
Family Protection | Also known as 'Life Income', this is a form of Life Cover with a regular and ongoing (eg. monthly) payout instead of a one-time lump sum. | |
4 |
Trauma Cover | Provides a lump sum payment if the insured person suffers a critical illness or injury. |
|
5 |
Total & Permanent Disability | Provides a lump sum payment if the insured person becomes totally and permanently disabled. | |
6 |
Income Protection | Provides financial support in the event that the insured person is unable to work (eg. due to illness). |
|
7 |
Mortgage Repayment Cover | Covers the cost of mortgage payments in the event that the insured person is unable to pay them (eg. due to loss of income). | |
8 |
Redundancy Cover | Provides financial support in the event that the insured person loses their job through involuntary redundancy. | |
9 |
Waiver of Premium | Covers the cost of insurance payments in the event that the insured person is unable to pay them. | |
10 |
Specific Injury Cover | Provides a lump sum payment if the insured person suffers a specific injury (or is diagnosed with a specific condition) from a predefined list. |
Version History
The table below details the history of updates made to the Quote Engine API:
| Prod Release | Provider | Benefits | Description |
| In testing | nib |
|
New rates for Health Cover nib are releasing their Q2 2024 rates for Ultimate Health, Ultimate Health Max, and optional add-ons.
Effective from: |
| In testing | Chubb Life |
|
Multi-Benefit Discount campaign extended again Chubb have extended their temporary Multi-Benefit Discount campaign by a further 3 months until 30th June 2024. |
| In testing | Chubb Life |
|
Added support for 'Lifetime Reward' discount On 26 June 2023, Chubb implemented a new 10% 'Lifetime Reward' discount for eligible clients who meet the following criteria:
To enable this on a quote, a new |
| 2024-02-08 | Asteron Life |
|
New rates for base Trauma Cover Asteron are releasing new rates for base Trauma Recovery (both
Effective from: |
| 2024-01-08 | Chubb Life |
|
Multi-Benefit Discount campaign extended again Chubb have extended their temporary Multi-Benefit Discount campaign by a further 3 months until 31st March 2024. |
| 2023-12-21 | nib |
|
New rates for Health Cover nib are releasing their Q1 2024 rates for Ultimate Health, Ultimate Health Max, and optional add-ons.
Effective from: |
| 2023-10-18 | Partners Life |
|
TPD Add-on is no longer inclusive Previously, the 'TPD Add-on' option under Trauma Cover was inclusive. Partners Life have now made this optional. Quotes without this option enabled will now return cheaper premiums. |
| 2023-09-29 | Chubb Life |
|
Multi-Benefit Discount campaign extended Chubb have extended their temporary Multi-Benefit Discount campaign by 3 months until 31st December 2023. |
| 2023-09-29 | nib |
|
New rates for Health Cover nib are releasing their Q4 2023 rates for Ultimate Health, Ultimate Health Max, and optional add-ons.
Effective from: |
Older entries are archived and can be provided upon request.