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

  • 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 whitelist-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" : Policy2Response
  "policyExposurePerils" : [PolicyExposurePerilPricingRequest]

  // Optional
  "endorsementLocator" : string
  "quoteLocator" : 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 previewEndorsementPriceUsingPOST and previewRenewalPriceUsingPOST endpoints will not have locators created and so these fields will be ommitted.

PolicyExposurePerilPricingRequest

{
  // Required
  "exposureCharacteristicsLocator" : string
  "perilCharacteristicsLocator" : string
  "policyCharacteristicsLocator" : 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 Policy2Response.

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

{
  // Required
  "premium" : string

  // Optional
  "commissions" : [ExternalRaterCommissionResponse]
  "technicalPremium" : string
}

The premium property is required for each peril characteristic while technicalPremium and comissions are optional in the response.

ExternalRaterCommissionResponse

{
  // Required
  "amount" : string
  "recipient" : string
}

Note

All values should be returned as an annualized amount. The Socotra platform will prorate these amounts based on the period of coverage and use the provided values to calculate taxes, fees, and unearned premium for the policy.

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.