Overview

To provide customers with access to Embed, an Embed URL is required. There are two types of URLs you can create:

• Embed authenticated flow - Suitable when the customer's identity is known. A unique URL is generated for the customer, granting them access to all Embed workflows. Must be used for Embed | Management and optional for Embed | Sales.
• Embed unauthenticated flow - Used when the customer's identity is unknown. This method is restricted to the Embed | Sales only.

📘

Test your Embed flow in Root's sandbox environment

You can preview your Embed flow in Root's sandbox environment without setting up authentication. Simply log into the dashboard, select the product module, choose embed from the sidebar, and click the Generate draft URL button. This must not be used in a production environment due to the URL containing a sensitive API key.

Implementing Embed involves the following steps:

1. Create an API key - Start by creating an API key using the Embedded insurance Embedded insurance : Create url.
2. Generate the URL - For each customer, generate a unique URL. This URL remains valid for 24 hours and grants the customer access to the flows detailed in the overview.
3. Embed the URL - integrate the URL either as a link on a standalone website you are hosting or within an iframe of an existing website.

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.

This API key must only include the Embedded insurance : create_url permissions.

Step 2: Generate the URL

In order to generate a URL for Embed, you will need to make a request to the endpoint documented below, using the API key you created in Step 1.

The default generated embed URL will direct the customer to the landing page. However, if you want the URL to lead directly to the issuing flow, for instance, include the custom_path parameter in the request body.

🚧

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 customers. If the API key is compromised please ensure that you delete the existing key from your organisation and generate a new one.

📘

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://{embed_url}&draft_definition=true.

Read more about the difference between the draft and live versions of a product module definition in the Workbench dashboard guide.

Embed authenticated flow

The Embed authenticated flow is used when you can identify the customer. You will need to include the identifying data when creating the URL. This will create a customer specific URL, and can be used to access all Embed workflows.

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": "/issue-policy?draft_definition=true" //Only include the draft_definition parameter when testing.
}

The endpoint will return the URL in the response body as embed_url. The URL will expire after 24 hours. The customer will be restricted from issuing policies for and accessing data related to the policyholder whose ID number matches the ID number provided in the request.

Embed unauthenticated flow

The Embed unauthenticated flow is used when you do not know the identity of the customer. This type of URL is restricted to the Embed | Sales flow only. The customer will be asked to enter their unique identifier based on the identification type configured on the product module. If the customer is not already a policyholder in your organisation, they will be asked to enter their personal details. If the customer already exists as a policyholder they will be notified and given the option to continue without filling in their personal details.

Request body

You will need to specify that you are using the unauthenticated flow in the request body.

{ 
  "unauthenticated": true,
  "product_module_key": "dinosure",
  "custom_path": "/issue-policy?draft_definition=true" //Only include the draft_definition parameter when testing.
}

The endpoint will return the URL in the response body as embed_url.

Step 3: Embed the URL

📘

Embed configuration

To customise your Embed workflow head to the Embed configuration guide.

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.

<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-labelled onboarding flow in the middle.

Below is an example of how this can be implemented.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script>
      // NB! This is for demonstration purposes only, your Root API key must not be made available client side
      function generateEmbedIframe() {
        const url = "<link to root api>";
        const apiKey = "<your api key>";

        const data = {
          unauthenticated: true,
          product_module_key: "dinosure_embedded",
        };

        fetch(url, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            authorization: `Bearer ${apiKey}`,
          },
          body: JSON.stringify(data),
        })
          .then((response) => response.json())
          .then((data) => {
            const iframe = document.createElement("iframe");
            iframe.src = data.embed_url;
            const div = document.getElementById("iframe-container");
            div.appendChild(iframe);
          });
      }
      generateEmbedIframe();
    </script>

    <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;
      }

      #iframe-container {
        width: 100%;
        height: 100%;
      }

      /* 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%;
        width: 100%;
      }
    </style>
  </head>

  <body>
    <div class="header">
      <h1>Example site</h1>
    </div>

    <div id="iframe-container">
      <!-- We will append the iframe here after generating the url -->
    </div>

    <div class="footer">
      <span>made by <a href="https://root.co.za">Root</a></span>
    </div>
  </body>
</html>