Picture

Introduction to the Sentro API Developer Guide

This page aims to give you an overview of the Sentro API so you can begin consuming APIs listed in the API documentation. This guide can be used by business analysts and system architects to find details on Sentro's RESTful APIs, which make it easy to integrate with Sentro. 

Using this API

The Sentro API is a REST based API that supports HTTPS requests via JSON data structures. All Sentro operations are supported via REST endpoints. Most requests acces JSON data as inputs and will usually return a JSON response.

URLS

There are two environments that are used in Sentro, each with their own URL. The request library between the two environments is kept as consistent as possible except when new features and improvements are being tested in Staging:

  • Staging Endpoint: https://api-staging.sentro.co

  • Production Endpoint: https://api.sentro.co

Authentication and Authorisation

All requests, except those prefixed by /authentication, require authentication. Sentro's API uses JWT token based authentication.

You client must obtain a JWT token a username and password using the /authentication endpoints which is then included in subsequent requests in the Authorization header as a bearer token

Authorization: Bearer <token>

The token's lifetime is only 24 hours (the expiry date can be found as exp data in the token's payload). In order to continue to access Sentro without new authentication requests, you can use the single use refresh_token in order to generate a new authentication token.

 Data Formats

The following simple data formats are described below:

  • Timestamps/DateTimes/Dates: Integer of number of unix seconds since epoch

  • IDs: Always unique integers

  • Codes: Always unique strings

Object Model

Sentro operates using three core classes of models (denoted in the image below by orange, green, and blue) :

Picture

User Data

User data is the most important aspect of our data sets - the user is the key to everything. As Sentro is intentionally designed to operate with all types of general and specialised insurance lines, as well as operate in applications where there is no insurance, the user model is intentionally designed to be as generic but extensible as possible

At the core to our user data is three primary attributes that are mandatory; email address, first name, and last name - everything else is configurable as required by your application of the Sentro product.

User attributes are how most customers store data, these are entirely configurable data fields that are configured at an organisation level to maintain properties on your users. User attributes are structured key value pairs where the value can be any of the following formats:

  • String

  • Date

  • Numeric

  • Boolean

User attributes can be created and maintained by you in your instance of Sentro. For example, here are some default user attributes that Sentro include by default:

  • Personal Email Address

  • Gender

  • Date of Birth

  • Employment Start and End Dates

  • Annual Salary

You control how the requiredness of these attributes by setting them to be any of the following on an Organisation basis:

  • Optional - users and administrators can enter data when necessary

  • User Required - users can be created in Sentro without this data, but the User is forced to fill this data in on the user's first login to our user portals

  • Required - Users cannot be created in Sentro without this data included

Users can have different roles with different organisations, a user can be a member of one, and administrator of another, and a broker with a third. The primary role of the user is the one with the highest permission.

Organisation Data

Organisation constructs are how Sentro group and organise users and is also the level at what configuration is applied to in Sentro.

Our organisations structure is a tree structure, an organisation can be a child of another organisation, which may be a child of another. Configuration, permissions and permissions work down organisations in the tree, e.g. user attribute rules set at a parent will automatically be set for child organisations unless the are overriden and admins of the parent organisation will automatically get the same access to child organisations - this makes configuring and managing large organisation lists easy.

Like users, the default organisation data model is also very simplistic, requiring only a name, type, and a primary user (called an Organisation Owner). It can further be extended by adding custom data using organisation attributes in a similar way to how the user profile can be extended using user attributes.

Various settings that can change the behaviour of Sentro are all applied at the organisation level. This includes:

  • Portal theming settings

  • Document templates

  • Email templates

  • Access settings for the organisation's users 

Insurance Data

Insurance Data models are more complicated due to the necessity of structured data for their effective operation. At a high level everything is grouped under an Insurer, a record of an insurance entity that provides product(s) to organisations and users in Sentro.

An insurer may have one or more Product Families, logical groupings of products that are sold together, this is purely for groupings and filtering.

Each product family will have one or more Products, products are the templated product information that the users's insurance plan is derived from. The product are used at plan products when assigned to users, plan products are the atomic insurance element of Sentro.

Plan products are associated with billing information in the way of rate cards to work as billable entities in a given plan. There are two types of plans, Master Plans which are parent plans held by an organisation, or Child Plans which are directly associated with a user. Child plans are usually derived from Master plans in the case of traditional group insurance and will inherit certain aspects.