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:

1. 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.
2. 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.
3. 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.

📘

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.

Request body

The request body must be a JSON object with the following properties.

{ 
  "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>