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.


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


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:

operation string new_business | endorsement | renewal | reinstatement
policyExposurePerils [PolicyExposurePerilPricingRequest]
tenantTimeZone string

endorsementLocator string
newPaymentScheduleName string
quoteLocator string
renewalLocator string


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.

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:

pricedPerilCharacteristics map<string,ExternalRaterPricedCharacteristics>

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.

exactPremium string
yearlyPremium string
yearlyTechnicalPremium string

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

recipient string

yearlyAmount string


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.


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


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.




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


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


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


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.