External Rater

Socotra provides a facility to price new business, endorsements, and renewals by making a synchronous API call out to an external web service rather than implementing the premium calculation logic in a plugin or Liquid template.

Socotra’s external rater endpoint automatically manages the specific characteristics that need to be priced, performs the proration, and handles any out-of-sequence endorsement operations out of the box.

Implementation

To set up the external rater, do the following:

  • Stand up a web service that accepts requests from the Socotra API for all pricing requests

  • Create the external rater configuration with a unique name, identify the URL endpoint and optionally, set one more headers to be sent with the request (to be used for authentication or other purposes) via the UI Administrative Panel or Integrations API.

  • Include the entry "externalRater": "<external_rater_name>" in the policy.json file associated with the product for which the external rater service will be used.

Note

The IP address that will be sending requests to the external rater is not guaranteed to remain fixed. Contact Socotra before adding allowlist-based security to your external rater.

Requests Sent to the External Rater

An external rater request contains the entire policy JSON object as well the specific characteristic references that need pricing. The synchronous call from Socotra will be a HTTP POST call submitted to the URL configured via the Socotra Administration UI.

The following payload will be sent to the customer’s external rater service:

ExternalRaterPriceRequest
required
operation string new_business | endorsement | renewal | reinstatement
policy PolicyResponse
policyExposurePerils [PolicyExposurePerilPricingRequest]
tenantTimeZone string

optional
endorsementLocator string
newPaymentScheduleName string
quoteLocator string
reinstatementLocator string
renewalLocator string

Note

The endorsementLocator and renewalLocator fields are only included when an endorsement or renewal object is created, using the Endorsements API and Renewals API respectively. The legacy Preview endorsement price and Preview a renewal's pricing endpoints will not have locators created and so these fields will be omitted.

PolicyExposurePerilPricingRequest
required
policyCharacteristicsLocator string
exposureCharacteristicsLocator string
perilCharacteristicsLocator string

This object contains the locators for the peril characteristics that need to be priced. They can be used to look up other information in the PolicyResponse.

Response Expected from the External Rater

The response from the external rater service must conform to the following:

ExternalRaterPriceResponse
required
pricedPerilCharacteristics map<string,ExternalRaterPricedCharacteristics>

optional
exceptionMessage string

The pricedPerilCharacteristics property is a map of the peril characteristics locators that are being priced to the specific pricing information.

The exceptionMessage property is optional and should only be sent to signal the the rating request failed. This message will be available through the Socotra API and also will be displayed in the UI if the request originated from the UI.

ExternalRaterPricedCharacteristics
optional
commissions [ExternalRaterCommissionResponse]
exactPremium string
exactTechnicalPremium string
yearlyPremium string
yearlyTechnicalPremium string

A premium value (yearlyPremium or exactPremium) is required for each peril characteristic, while technical premium and commissions are optional. See Premium Calculations for details on these properties and the way in which yearly and exact values relate to each other.

Note

premium and technicalPremium are accepted as aliases for yearlyPremium and yearlyTechnicalPremium, respectively. We recommend using the latter property names to reduce potential confusion about the meaning of these amounts.

ExternalRaterCommissionResponse
required
recipient string

optional
exactAmount string
yearlyAmount string

Socotra Administration UI

The Socotra Administration UI can be accessed from the Administration link, located at the top-right banner of the login page of a tenant.

../_images/5.png

The “Manage Integrations” application allows the user to setup the link to the external rater web service.

../_images/6.png

To add an external rater, choose a unique name (to be referenced in policy.json) and provide the full URL of a webservice that conforms to the specification below. The headers capability allows the service to be secured. The screenshot below shows a service with basic authentication.

Attribute

Description

name

The name is used in policy.json to select the correct rater for this product.

url

The URL exposes a POST service that is called by Socotra to retrieve premiums and commissions.

headers

The headers can be used to provide security information, parameters, and other information to the service.
../_images/7.png

Socotra Configuration

The final step is to add the rater to the policy.json file for the product that will be using the new rater.

{
  "fields": [],
  "documents": [],
  "externalRater": "my-rater"
}

Error Handling

Socotra checks responses sent from external raters for the field exceptionMessage. If this field is found, the Socotra API will return an HTTP 409 error back to the client, with the error message in the message field. In addition, this message will be displayed to the user in the Socotra UI if the transaction originated from the UI.