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 or year.

    • 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 of month 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 any periodic specified.

  • groupByTenant - takes a boolean flag true or false.

    • 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 to true 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 the groupByTenant flag set.

  • groupByProduct - takes a boolean flag true or false.

    • 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 to true 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 the groupByProduct 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 or test.

    • 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.

MetricRequest
required
startTime datetime
endTime datetime
localEndDateAdjusted string
localStartDateAdjusted string

optional
groupByProduct boolean?
groupByTenant boolean?
periodic Enum? none | day | week | month | quarter | year
tenantType Enum? test | production | retired | deleted
currencies string[]?
products string[]?
tenantLocators uuid[]?
MetricResponse
required
count int
endDate string
offset int
periodic Enum none | day | week | month | quarter | year
startDate string
results DataPoint[]
DataPoint
required
tenantLocator uuid
productName string
currency string
dataPointStartDate string
value number

Metric Definitions

Gross Written Premium

Definition: The sum of all charges of category premium generated by transactions whose issuedTime falls within the specified period. Charges in Socotra are generated during the processing of transactions, and they can be both positive and nagative. The GWP metric for a period will include charges from all transactions, this includes new business, cancellation, reinstatement, renewal and mid-term changes. Premium charges related to both cancellation and mid-term changes may be negative.

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.