> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.nibtravelinsurance.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.nibtravelinsurance.com/_mcp/server. # 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. This can be used to support both standalone sales funnels as well as integration into bundled sales opportunities. ## Quick start guide - Getting started To get started with a basic quote request the following request can be sent to the [Quotes API](/reference/quotes-api/quote/create-update-quote) 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](/guides/quote-and-booking-flows/country-list) ```javascript { "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: ```javascript 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: ```javascript "quote": { "id": "274ba4ce-8937-462a-949a-1e87e845a23c", "isNew": false, "isPurchased": true, "hasConfigChanged": false, "isPurchaseInitiated": true, "clientSessionId": "a8235a14-406c-46a0-9ee2-456ce8e0cc9c", "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](/guides/quote-and-booking-flows/options) * Credit card tokenisation flow to the card token API [Credit card tokenisation API](/guides/quote-and-booking-flows/taking-payments) * Purchase request utilising the tokenised credit card information.[Purchase API](/reference/quotes-api/purchase/quote-purchase) ```mermaid sequenceDiagram Client->>+Users API: Retrieve access token {customerInterfaceId, userTypeID, Client_id, grant_type, username, password} (2) Users API->>+Client: access token (2) Client->>+Quotes API: Retrieve a quote - {access token} (3) Quotes API->>+Client: Quote with prices (3) Client->>+Quotes API: Retrieve a quote with options (4) Quotes API->>+Client: Quote with prices, plus options (4) Client->>+Card Token API: Tokenise credit card input data (5) Card Token API->>+Client: Card token (5) Client->>+Quotes API: Purchase request including tokenised credit card information (6) ``` ## 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](/reference/products-api/plan/policy-benefit). 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. ```mermaid sequenceDiagram Client->>+Products API: Retrieve a list of benefits for a product (Plan Id) Products API->>+Client: Benefits with limits, description ``` ## 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. ```javascript { "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: ```javascript https:///?token= ``` We recommend to make use of the [interchange token end point](/reference/quotes-api/interchange/get-v-1-brand-code-interchange) to retrieve a Quote object for the token. The sample response is here: ```javascript { "category": "Success", "data": { "quoteReferenceNumber": "QNIB002440", "quote": { "id": "2b8dbb77-84a6-4036-b1fa-90c98c9236a7", ... "input": { ... }, } } } ```