Quote and purchase flows

This section documents use-cases about embedding quote and purchase paths and providing a more tightly integrated user experience, allow for improved user experience and increased conversion rates.

Quick start guide - Getting started

To get started with a basic quote request the following request can be sent to the Quotes API with a simple sample request. This will return a list of plans available for this quote request:

There are two quote types supported to retrieve single trip and annual multi-trip plans:

SINGLETRIP
MULTITRIP

A sample request is shown below, note that country codes are defined in the Country list API

Copy

Copied

{
    "stage": "INITIAL",
    "input": {
        "quoteType": "SINGLETRIP",
        "homeAddress": {
            "countryCode": "AUS"
        },
        "destinationCountryCodes": [
            "ESP"
        ],
        "policyHolders": [
            {
                "isPrimary": true,
                "isDependent": false,
                "age": 33
            }
        ],
        "departureDate": "2023-05-27",
        "coverEndDate": "2023-06-26"
    }
}

To set a specific plan on subsequent quote requests, which should be done before selecting additional options you can set the plan Id in the subsequent requests to be:

Copy

Copied

body.input.planId = body.prices[1].planId;

The planId will be specific to the brand code and specific products offered, it is recommended to retrieve this dynamically and not hard code it in the API integration.

Quote stages

Quote stages can be used to set stages in the quote, these can be useful for restoring the position

INITIAL - This is used for initial quote creation after entering basic details for the quote
BASEQUOTE - This is used for when a plan selected has been returned.
OPTIONS - This is for when a plan has been selected and options are been added to the existing quote.
DETAILS - This is for when traveller details are been entered.
MEDICAL_SCREENING - This is for when traveller initiates medical screening and remains in the medical screening flow (including resume and completing screening).
PAYMENT - This is for when payment is been taken on the quote.

Policy number on Payment

You can retrieve the policy number to display to the customer returned from the API upon purchase by utilising the policyNumber attribute returned as part of the response of the Purchase API.

An example return response showing an example of the policyNumber attribute been returned by the purchase API call is shown below:

Copy

Copied

    "quote": {
        "id": "274ba4ce-8937-462a-949a-1e87e845a23c",
        "isNew": false,
        "isPurchased": true,
        "hasConfigChanged": false,
        "isPurchaseInitiated": true,
        "clientSessionId": "a8235a14-406c-46a0-9ee2-456ce8e0cc9c",
        "policyNumber": "<PolicyNumber>",
        "stage": "PAYMENT",
     ...
    }

Quote and purchase flow

The sequence flow for retreiving a quote is typically the following. The sequence is the following:

Client needs to have username and password to retrieve access token
Call is made from client to the user API endpoint to get an access token using user credentials (username and password). Sample requests and parameter details available at Authorization
Use this token as a bearer token while making a call to retrieve a quote based on supplied parameters including trip dates, destination country, country of residence. (If applicable to the brand). A list of available products with detailed pricing information will be returned with all available plans. Quotes API
Select a plan, add options to the quote and retrieve the updated pricing information Options
Credit card tokenisation flow to the card token API Credit card tokenisation API
Purchase request utilising the tokenised credit card information. Purchase API

Retrieving product benefits

The following sequence can be used to retrieve product benefits. It can include the following information:

Benefit name
Benefit description
Benefit limit and sub-limits

To access plan benefits it is recommend using the Product benefits by Plan API. The plan ID parameter is passed back from the Quote response and applies to the individual plan documenting the detailed benefit and limits available.

This can be used to avoid hard coding benefit limits in integrated purchase paths.

Policy documentation

To provide detailed policy specific documentation, including product disclosure statements, the Products API can be used to provide contextual links to display to the customer. To access policy wording for a choosen insurance contract you can access it by going to PDS link.

Medical screening

It is recommended that a URL redirect be introduced to support medical screening of pre-existing conditions if this capability is required.

Accepting Terms and conditions

To accept terms and conditions it is advisible to use the property "hasAcceptedTermsAndConditions" and set it to "true" in the Quote input Request. Note that this value should be set to true once all the T&C's options are selected by the user.

Copy

Copied

{
    "stage": "DETAILS",
    "input": {
        ...
        "hasAcceptedTermsAndConditions":true,
        ...
    }
}

Retrieving Quote on a hosted Purchase Path

In order to support the hosted purchase path usecases to retrieve a quote, then are few steps to follow. The potential usecases are:

When redirecting to the hosted purchase path via email a quote flow
When redirecting back to the hosted purchase path on completion of the medical screening flow

The example redirect URL will be like below:

Copy

Copied

https://<Partner Quote Line URL>/?token=<interchange token>

We recommend to make use of the interchange token end point to retrieve a Quote object for the token.

The sample response is here:

Copy

Copied

{
    "category": "Success",
    "data": {
        "quoteReferenceNumber": "QNIB002440",
        "quote": {
            "id": "2b8dbb77-84a6-4036-b1fa-90c98c9236a7",
            ...
            "input": {
            ...
            },        
        }
    }
}