Embed implementation
Add Embed to your existing customer journey
Overview
To give customers or end-users access to Embed, you will need an Embed URL. You can generate this URL in one of two ways:
- JWT authentication URL - This allows you to authenticate a user and generate a policyholder-specific URL to access Embed. The user gains access to all Embed worfklows for that policyholder.
- Open Embed URL - This allows any user who visits your site to issue a policy via a generic URL. Users are restricted to issuing policies only, and cannot access other Embed workflows.
In both cases, implementing Embed involves the following steps:
- Create an API key - The required API key permissions differ depending on whether you want to use a JWT authentication URL or an open Embed URL.
- Generate the URL - If you are using JWT authentication, you will need to request a new URL for every customer. If you are using an open Embed URL, you can simply append the API key to a generic URL as a query parameter.
- Embed the URL - You can embed the URL as a link to a standalone website or in an iframe.
Embed configuration
To customise your Embed workflow head to the Embed configuration guide.
Step 1: Create an API key
Please follow the steps outlined in the getting started guide in the API reference to create an API key.
Make sure that you enable only a single permission when creating the API key, depending on the type of URL you want to use:
- For JWT authentication, enable only the
Embedded insurance : Create url
permission - For open Embed, enable only the
Embedded insurance : Create
permission
Note: If any additional permissions are selected, you will see an authorisation error when attempting to access the Embed sales flow.

Embedded insurance API key permissions
Test your Embed flow in Root's sandbox environment
You can test your Embed flow in Root's sandbox environment by using a sandbox API key. A sandbox API key always starts with
sandbox_...
. You can safely experiment in sandbox mode without worrying about issuing "real" policies. Premiums are not collected for sandbox policies.Read more about Root's sandbox environment in the Workbench dashboard guide.
Step 2: Generate the URL
JWT authentication
If you are using JWT authentication, you will need to make a request to the endpoint documented below to generate a URL for each customer, using the API key you created in Step 1.
When generating the embed URL you also have the option to specify a custom URL path. By default, the generated embed URL will navigate the user to the landing page. If you would like the URL to navigate directly to the issuing flow (for example), you should include the custom_path
body parameter.
Method | POST |
URL | {host}/v1/insurance/embed/url , where host is either https://sandbox.rootplatform.com for sandbox policies, or https://api.rootplatform.com for live policies. |
Authentication | Basic Auth - Use your API key as the username, and leave the password blank. |
Request body
The request body must be a JSON object with the following properties.
Property | Definition |
---|---|
identification_number | string. This must match the value of policyholder.id.number of the policyholder object on Root |
identification_country | string. The ISO Alpha-2 matching the value of policyholder.id.country of the policyholder object on Root. If this field is omitted it will default to "ZA" |
identification_type | string. This must match the value of policyholder.id.type of the policyholder object on Root. If this field is omitted it will default to "id" |
product_module_key | string. The unique identifier of the product module. Must match the value of quote_package.module.type on the quote package object or policy.module.type on the policy object . |
custom_path optional | string. The custom path if the URL should navigate to a different page than the Embed landing page. |
{
"identification_number": "7203065775085",
"identification_country": "ZA",
"identification_type": "id",
"product_module_key": "dinosure",
"custom_path": "https://dinosure.io/quote/cover"
}
The endpoint will return the URL in the response body as embed_url
. The URL will expire after 24 hours. The user will be restricted to issuing policies for and accessing data related to the policyholder whose ID number matches the ID number provided in the request.
Ensure that the API key is not stored client side
It is strongly advised to make this request server side and ensure that the API key is not stored client side as it is used to authenticate users. If the API key is compromised please ensure that you delete the existing key from your organisation and generate a new one.
Open Embed
For open Embed, the URL to your embed flow has the following format: https://app.embedroot.com/{PRODUCT_MODULE_KEY}?api_key={YOUR_API_KEY}
.
For example, https://app.embedroot.com/dinosure_embedded?api_key=sandbox_NDM1YzAzNTMtYmE3MS00ZjZiLTk2ODItZGQ4Zjk4NDQ5YTNhLkxnUTJmM210N1hPZWtmYUhQUWtGMTBaZ0ZZejlBX0xD
.
Anyone accessing this link will be restricted to the policy issuing flow only.
Testing your Embed flow using the draft product module definition
To point your Embed flow to the latest draft product module definition, you can add the query parameter
&draft_definition=true
to the embed URL (this only works when using a sandbox API key). For example,https://app.embedroot.com/{PRODUCT_MODULE_KEY}?api_key={YOUR_API_KEY}&draft_definition=true
.Read more about the difference between the draft and live versions of a product module definition in the Workbench dashboard guide.
Step 3: Embed the URL
Once you have generated the URL, you can embed it into your existing customer journey in one of two ways.
Option 1: iframe
This URL can then be provided to an iframe via the src attribute.
html<iframe src="{EMBED_URL}"></iframe>
Option 2: Link to open as a standalone website
This option can be used to embed the URL as a button link, QR code or any other method. For an example, please visit our Dinosure implementation.
<a href="{EMBED_URL}">Get insurance cover</a>
Full-page example
The flow can be embedded between your existing header and footer in order to keep your brand and URL, slotting the white-labeled onboarding flow in the middle.
Below is an example of how this can be implemented.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Dinoparks</title>
<style>
html,
body {
margin: 0;
padding: 0;
font-family: sans-serif;
}
/* Set up “body” as a flexbox */
body {
display: flex;
height: 100vh;
flex-direction: column;
flex-wrap: nowrap;
justify-content: space-between;
}
/* Style your existing header */
.header {
height: 80px;
background-color: #4078fa;
color: white;
display: flex;
justify-content: left;
align-items: center;
padding: 0 1em;
}
/* Style your existing footer */
.footer {
background-color: #4078fa;
color: white;
text-align: center;
padding: 1em;
}
/* Slot the iframe in the middle */
iframe {
display: block;
border: 5px solid #e7e241;
height: 100%;
}
</style>
</head>
<body>
<div class="header">
<h1>Example site</h1>
</div>
<!-- Replace iframe src with your url -->
<!-- Either via the JTW authentication approach -->
<iframe src={{response.embed_ur}}></iframe>
<!-- Or using the Open Embed Link -->
<iframe src="https://app.embedroot.com/dinosure_embedded?api_key=sandbox_NDM1YzAzNTMtYmE3MS00ZjZiLTk2ODItZGQ4Zjk4NDQ5YTNhLkxnUTJmM210N1hPZWtmYUhQUWtGMTBaZ0ZZejlBX0xQ"></iframe>
<div class="footer">
<span>made by <a href="https://root.co.za">Root</a></span>
</div>
</body>
</html>
Updated 29 days ago