Metrics
Socotra’s Metrics APIs provide visibility into a variety of key business metrics across the entirety of your environment, without the need for any preconfiguration. Reports can be run on GWP, Quote & Policy counts among others, with options to aggregate on a variety of levels including tenants, products and time periods.
Overview
The following metrics are currently available;
Gross Written Premium
Issued Policies
Priced Quotes
New Business Conversion Rate
Issued Renewals
Expired Policies
Renewal Rate
These metric reports can be consumed as raw data via API, or as visualizations via the Reporting Workbench, both of these options also support the export of result data in csv format.
API Usage
Regardless of the metric, the desired time range that the query should cover must be specified in the request body via the mandatory startTime
and endTime
parameters. All other request parameters described below are optional.
Time filtering behaves inclusive on the left, exclusive on the right, meaning startTime : 2024-01-01
and endTime : 2025-01-01
will include all of Jan 1st 2024, and none of Jan 1st 2025.
Warning
While mertic requests can cover future periods, the service design has been optimized for retrospective reporting. Result sets for rates that are future looking are susceptible to distortion and are not recommended or supported.
Within the requests there are a variety of ways to specify how the returned results should be strucutred, these options generally fall into two categories, aggregations and filters.
Aggregations
Aggregation parameters afford control over how the result set is broken out into differrent groups, the options here include;
periodic - takes a single value from the enum list of
none
,day
,week
,month
,quarter
oryear
.Will break results into brackets of time per the periodic specified. e.g. a request for Gross Written Premium over a one year time frame with the
periodic
ofmonth
will return a result set of 12 values, each showing the Gross Written Premium for the respective month. The sum of the amounts in the result set will equal the amount returned had the request been made without anyperiodic
specified.
groupByTenant - takes a boolean flag
true
orfalse
.If set to true the results are broken out into sets representing each tenant that contributed data. e.g. In an implementation with multiple tenants deployed, a request for Gross Written Premium over a one year time frame with the
groupByTenant
flag set totrue
will return a result set with values for each distinct tenant. The sum of the amounts in the result set will equal the amount returned had the request been made without thegroupByTenant
flag set.
groupByProduct - takes a boolean flag
true
orfalse
.If set to true the results are broken out into sets representing each product that contributed data. e.g. In an implementation with multiple products deployed, a request for Gross Written Premium over a one year time frame with the
groupByProduct
flag set totrue
will return a result set with values for each distinct product. The sum of the amounts in the result set will equal the amount returned had the request been made without thegroupByProduct
flag set.
Note
Aggregation parameters are not mutually exclusive and can be used in combination.
Filters
Filter parameters afford control over what whether data from certian sources should be included or suppressed from the result sets, the options here include;
tenantType - takes a single value from the enum list of
production
ortest
.Will ensure that result data is only sourced from tenants of the type specified in the request.
tenantLocators - takes an array of tenant locators.
Will ensure that result data is only sourced from tenants specified in the request.
products - takes an array of product names.
Will ensure that result data is only sourced from entities (quotes, policies, transaction, charges etc) associated with the products specified in the request.
currencies - takes an array of ISO 4217 currency codes.
Only applicable to the GWP metric. Will ensure that a distinct result set per currency code specified will be included in the response (assuming that charges in that currency exist and are captured in the broader result set).
Backfill Zero
Sparse data sets or requests that uilize more granual periodics such as day
or week
are more likely to contain observation gaps in the result set. To deburden direct UI consumtion of the APIs from having to deal with observation gaps, the service supports a backfillZeroes
query parameter in the endpoint url.
Default to false, if set to true the system will inject an observation with a value of 0
into the result set.
Warning
In order to protect system performance there is a limit of 55 imposed for backfilling zeros that will apply to any sub-set of observations. When requesting a result set for a one year period, the system will support backfilling in combination with a periodic of years
, quarters
, months
or weeks
. A periodic of days
in such cases is not supported because the number of observations will exceed 55.
requiredstartTime datetimeendTime datetimelocalEndDateAdjusted stringlocalStartDateAdjusted stringoptionalgroupByProduct boolean?groupByTenant boolean?periodic Enum? none | day | week | month | quarter | yeartenantType Enum? test | production | retired | deletedcurrencies string[]?products string[]?tenantLocators uuid[]?
requiredcount intendDate stringoffset intperiodic Enum none | day | week | month | quarter | yearstartDate stringresults DataPoint[]
requiredtenantLocator uuidproductName stringcurrency stringdataPointStartDate stringvalue number
Metric Definitions
Issued Policies
Definition: The count quotes whose issuedTime
falls within the specified period.
Policies are created in Socotra when a quote is moved to the issued state.
Priced Quotes
Definition: The count of quotes which reached the priced
, or some subsecquent, state within the specified period.
Quotes that meet this criteria but are subsecquently discarded
or reset
will not be included in the count.
New Business Conversion Rate
Definition: The proportion of Priced Quotes that go on to become Issued Policies within the specified period. More specificially the rate is calcuated as the count of Priced Quotes in the specified period, divided by the count of Issued Quotes in that same specified period, where set of issued quotes is a subset of the identified priced quotes. Within a result set, a priced quote that gets assiged to a certian period, but whose issuance falls in a subsecquent period, will not contribute to the conversion rate of either period.
Issued Renewals
Definition: The count quotes renweal transactions whose issuedTime
falls within the specified period.
Policies are renewed in Socotra when a transaction of category renewal
is moved to the issued state.
Expired Policies
Definition: The count of policies where the endTime
of the latest term falls within the specified period.
If the endTime
was set via a cancelation transaction, the policy is not counted as an expiry and will not be counted
Renewal Rate
Definition: The proportion of policies elegible for renewal that went on to be renewed in within the specified period.
A policy is deemed elegible for renewal in a given period if either a) the policy was actually renewed in the specified period, or b) the endTime
of the latest term falls within the specified period.
Note
For the renewal rate the periodic parameter is mandatory, if it is not set - exception will be raised.