Overview

The prefill values feature enables you to enhance the user experience of the Sales add-on by injecting data into the iframe via query parameters. This can populate designated fields in the flow, saving users the effort of re-entering the same information. Additionally, you can use prefill actions to customize how fields behave when data is pre-populated.

Structure of the prefill values

There are 4 optional sections for prefill values:

Quote values

The quoteValues query parameter can be used to prefill values for the quote step. The specific keys to use depend on your quote schema, so you can pass in any values that match the schema's keys and data types. If all required quote fields are provided as prefill values, a quote will be generated automatically.

See example as follows:

{
 "cover_amount": 10000,
 "spouse": true,
 "<key>": "<value>"
}

Personal details values

The personalDetailsValues query parameter can be used to prefill values for the personal details step. The structure of this object must follow the provided example and all key-value pairs are optional. If you want to skip or automatically submit the personal details step, you can enable the personalDetails.displayOptionalSections.skipOnPrefill setting in the product module Embed config.

For guidance on data validation see the Policyholder object documentation.

{
 "first_name": "Erlich",
 "last_name": "Bachman",
 "identification_number": "8906115800088",
 "identification_country": "ZA",
 "identification_type": "identification", // identification || passport
 "identification_expiration_date": "2025-12-02",
 "email": "[email protected]",
 "cellphone_number": "0821234567",
 "gender": "male",
 "date_of_birth": "1989-06-11",
 "address_opt_in": true,
 "address_line_1": "5230 Penfield Avenue",
 "address_line_2": "Prefill Villa",
 "suburb": "Woodland Hills",
 "area_code": "8001",
 "city": "Cape Town",
 "country": "ZA",
 "policyholder_type": "individual", // individual || company
 // Company policyholder type specific fields
 "date_of_establishment": "2022-01-01",
 "registration_number": "PIEDPIPER001",
 "company_name": "Aviato",
 "subsidiary_companies": ["Pied Piper"],
 "contact_position": "Partner",
 "company_website_url": "https://www.piedpiper.com"
}

Application values

The applicationValues query parameter allows you to prefill values for the application step. The specific keys to use depend on your application schema, so you can pass in any values that match the schema's keys and data types. This allows you to prefill fields in the application step as long as the key and data type match the schema.

See example as follows:

{
 "spouse: ": {
   "first_name": "Monica",
   "last_name": "Hall",
   "date_of_birth": "1993-09-27"
 },
 "<key>": "<value>"
}

Payment values

The paymentValues query parameter can be used to prefill values for the payment step. The specific key-value pairs required depend on the payment method configured for the product module. Currently, the supported payment methods are debit order and external. The structure of the prefill values must match one of the examples provided, depending on the payment method being used.

Debit order example:

{
 "branch_code": "7898",
 "account_holder": "E Bachman",
 "bank": "Standard Bank",
 "debit_day": 5,
 "account_type": "cheque",
 "account_number": "1234"
}

External payment method example:

{
 "debit_day": 5,
 "external_reference": <value>,

}

Applying the prefill values

To apply prefill values, you can stringify an object and include it as the value for the relevant query parameter. Here is a basic JavaScript example showing how to to apply prefill values to a URL:

📘

Create baseURL

See Embed implementation for more details on creating the baseURL.

const baseUrl = 'https://app.embed-root.com/<organization_id>/?token=<jwt_token>&environment=sandbox';
 
const quoteValues = {
 cover_amount: 10000,
 spouse: true,
 '<key>': '<value>',
};
 
const personalDetailsValues = {
 first_name: 'Erlich',
 last_name: 'Bachman',
 identification_number: '8906115800088',
 identification_country: 'ZA',
 identification_type: 'identification',
 identification_expiration_date: '2025-12-02',
 email: '[email protected]',
 cellphone_number: '0821234567',
 gender: 'male',
 date_of_birth: '1989-06-11',
 address_line_1: '5230 Penfield Avenue',
 address_line_2: 'Prefill Villa',
 suburb: 'Woodland Hills',
 area_code: '8001',
 city: 'Cape Town',
 country: 'ZA',
};
 
const applicationValues = {
 'spouse: ': {
   first_name: 'Monica',
   last_name: 'Hall',
   date_of_birth: '1993-09-27',
 },
 '<key>': '<value>',
};
 
const paymentValues = {
 debit_day: 5,
};
 
const quoteString = `quote_values=${JSON.stringify(quoteValues)}`;
const personalDetailsString = `personal_details_values=${JSON.stringify(personalDetailsValues)}`;
const applictionString = `application_values=${JSON.stringify(applicationValues)}`;
const paymentString = `payment_values=${JSON.stringify(paymentValues)}`;
 
const prefilledUrl = `${baseUrl}&${quoteString}&${personalDetailsString}&${applicationString}&${paymentString}`;

Prefill actions

Prefill actions allow you to customize how a field behaves when it has been prefilled. By default, a prefilled field will remain visible and editable. You can use prefill actions to specify alternative behavior. The options are:

• hidden: If the prefill value is valid, the field will be hidden from the user. This can be useful for handling steps that are unnecessary for the user to see.
• disabled: If the prefill value is valid, the field will be visible to the user but disabled. This allows the user to see the prefilled value but not modify it.

To apply prefill actions to a schema, you can add a prefillAction key to the component's props object. For more information on schemas, see the Schemas overview documentation.

Here is an example of a quote schema with the prefill actions prop:

{
   "key": "cardio_fitness_level",
   "type": "radio",
   "label": "What is your cardio fitness level?*",
   "props": {
     "prefillAction": "disabled"
   },
   "options": [
   ],
   "outputPath": "cardio_fitness_level"
 },