Getting started

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.

You can get started now by following our getting started tutorial, which will guide you step-by-step to set up your own playground organisation on Root. As part of this process, a working toy product module ("Dinosure") will be created for you. You can use this product module to issue policies, open claims and test out a range of other Root features in our sandbox environment.

Once your Dinosure product is set up, you can create an API key and start interacting with it via our API.

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.

11341134

How to find the example request, example response, and response object schema for an endpoint.

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.

For our clients using the Root multi-tenanted environment, the following domains can be whitelisted:

  • Sandbox environment: https://sandbox.rootplatform.com/
  • Production environment: https://api.rootplatform.com/

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 the host https://sandbox.rootplatform.com/ instead of https://api.rootplatform.com/ for any requests. 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, and the live and draft versions of a product module, in the Workbench dashboard 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 limit the key to either the sandbox or production environment, and specify which permissions are available to the key.

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:

Property

Definition

type

string. Indicates whether the entity was created by a user, or an API key. Possible values are api_key or user.

id

string. The unique ID of either the user, or API key that created the entity.

owner_id
optional

string. An optional value included when type == "api_key", which indicates the organisation that owns the API key used to generate the entity.

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.

Query parameter

Definition

page_size
optional

integer. Defaults to 30. The maximum number of items that will be contained in a single page, between 1 and 100 (inclusive).

page
optional

integer. Defaults to 1. The page number of the entities to fetch. Must be a minimum of 1.