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.
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": 0,
"providerName": "string",
"providerLogoUrl": "string",
"hexColor": "string",
"hasErrors": true,
"policyFee": 0,
"vitalityFee": 0,
"totalPremium": 0,
"clients": [
{
"clientId": "string",
"clientName": "string",
"products": [
{
"clientBenefitId": "string",
"benefitId": 0,
"productId": 0,
"productName": "string",
"descriptions": [
"string"
],
"premium": 0,
"errors": [
{
"id": 0,
"message": "string"
}
]
}
]
}
]
}
],
"quoteId": "string",
"paymentFrequency": "string",
"calcTime": 0,
"apiVersion": "string"
}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