Skip to main content

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:

qe-quote-response-structure.png

  • Results – A successful response will contain one or more result objects. Each result relates to a specific provider (insurer) as defined by its providerId. This object contains the overall totalPremium for that provider, along with any applicable fees.

  • Clients – Each result is split out by the client object(s) contained within it, as provided during the request.

  • Products – Under each client is an array of product objects, based on the benefitId and productId values included in the request. This contains the itemised premium that 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 errors detailing 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

Back to top