Overview

Welcome to the Root Insurance API reference!

Root Insurance allows you to create and integrate insurance products into your product quickly. The platform issues policies, collects premiums, tracks events and conversations, and reports to the appropriate authorities, allowing you to focus on building an exceptional digital customer experience.

👍

We'd love to get your feedback

We are continually reviewing and improving our documentation. If you have any feedback, please use the "Suggest edits" button on the top right of the relevant page, or send an email to [email protected].

The Root API is based on REST using built-in HTTP features, like HTTP authentication and HTTP response codes.

This API reference is available as a single OpenAPI specification document at https://api.rootplatform.com/v1/docs/insurance/openapi.

Make your first request

Before you can interact with the API, you need to be added to an organisation on Root (all API requests are organisation specific). If you are part of an existing team building with Root, you can ask your team for your organisation details. You can also create your own playground organisation by following our getting started tutorial.

Once your organisation has been set up, please follow the steps in the authentication section to create a sandbox API key. You can use this key to test out the API in our sandbox environment.

Most of the API endpoints rely on existing data. For example, you can only retrieve a policy if policies have been issued in your organisation.

If you want to kick the tyres, a good place to start is the upsert a policyholder endpoint:

1. Add your API key to the "username" field under "Authentication" (you can leave the "password" field empty)
2. Select the request example next to "Request" (feel free to change the example values in the request body)
3. Click on "Try it"
4. You should see a successful response in the "Response" pane

To explore other requests in the policy lifecycle, we recommend that you start with the Dinosure tutorial. You will be guided through creating a toy product module that you can use to issue policies, open claims and test out a range of other Root features in our sandbox environment.

Navigating the interface

The interface for each endpoint allows you to easily view and copy example requests and example responses. You can also view an object schema explaining each property included on the response. Please see the screenshot below for more details.

Domains

Root is hosted on AWS cloud services with public highly-available APIs. When configuring firewall setups we'd recommend whitelisting the domain names for your instance.

Alternatively, you can whitelisting the entire *.rootplatform.com domain. Port: 443.

📘

Clients using Root Private Stack

If you are using our Private Stack, reach out to [email protected] for guidance on your domain names and other aspects of your setup.

Root's API is available on the public internet at the domains listed above, so only a valid API key is required for access. API keys are organisation and environment specific.

Environment

Working with an API that can issue real policies and move real money might be intimidating or risky to explore. Root has an environment called "sandbox mode" that allows you to safely integrate and test your products without having any physical effects.

To use the sandbox environment, use sandbox instead of api in the URL. Note that all the example requests in this API reference make use of the sandbox host.

All organizations are limited to the sandbox environment by default, pending live approval by the Root team.

Organization data is tightly isolated to each environment. To clear out your sandbox environment at any time, you can use the flush tool in the organization's settings.

You can read more about the sandbox and production environment in the Overview guide.

Authentication

Insurance on the Root platform is bound to organisations, which allow you to control access through API keys with fine grained permissions.

Generating API keys

To generate an API key, head over to your organisation dashboard, navigate to Settings > API keys, and click on "Create API key". When creating an API key you can specify which permissions are available to the key.

📘

Sandbox vs Production

Make sure you are in the correct mode on the dashboard to make a key specific to your environment need. API keys created in sandbox mode will be for the sandbox host only with the same rule applying to those created in production mode being for the api.rootplatform host only.

Once you've generated an API key, you can authenticate your requests using HTTP Basic authentication - use your API key as the username, and leave the password field blank.

Revoking API keys

If you no longer need an API key, or if your key becomes compromised, you can easily revoke it. Head over to your organisation dashboard, navigate to Settings > API keys, and click the trash icon on the API key you'd like to remove.

created_by field

As part of recording a full audit trail of insurance activity on the platform, a created_by field is included on policyholder, policy and claim objects. This field indicates either the user that created the entity through the dashboard, or the API key used to create the entity through the API. The created_by field is an object that contains the following fields:

Pagination

All list type endpoints are paginated, and can be controlled using the page_size and page query parameters. If omitted, the response will default to page_size=30 and page=1.