External Data Calls¶

Socotra can make calls to an external web api service to populate data.

Warning

External data calls are only available for new policies. They don’t apply to endorsements, or renewals.

Common use cases¶

Vehicle VIN lookup
Send an address to a database that computes flood probability
Look up the health information determine life insurance rating category

Overview¶

External data calls may be defined on policies, exposure, and perils. They are triggered by a change in a specified data field in the Fields list, and will populate a list of other fields, as specified in your configuration.

The external call is triggered:

When policy fields are updated in the Socotra UI while filling out an application manually
On a POST request to the Create Policy or Update Policy endpoint

All policy data is sent to the external web service, as are any relavent entity characteristics.

A wrapper is generally needed:

To handle authentication with the external service
To process results into the format Socotra expects

Note

External data calls cannot be triggered by or populate field groups.

Configuration¶

Add an “externalDataCalls” section to policy.json, exposure.json, or [myPerilName].json:

{
  "fields": [],
  "externalDataCalls": [
    {
      "triggerField": "triggerFieldName",
      "targetFields": ["field1", "field2", "field3"],
      "uri": "https://www.mywebservice.com/myendpoint"
    }
  ]
}
Attribute

Required

Valid Values

Description

triggerField

yes

field name

Changing this field triggers the external data call

targetFields

yes

array of field names

The fields to be populated with the response

uri

yes

URI locator

The location of the web service

Data structure sent to web service¶

Socotra sends a POST call which includes the full policy object and one “characteristics” object to the external service, matching which object the data call is defined on. Use this to take context into account when returning values from the external service. The data structure sent in the web service invocation has the following form:

ExternalDataCallRequest¶

{
  // Required
  policy : Policy2Response

  // Optional
  exposureCharacteristics : ExposureCharacteristicsResponse
  perilCharacteristics : PerilCharacteristicsResponse
  policyCharacteristics : PolicyCharacteristicsResponse
}

Data structure expected from web service¶

The web service’s response must have the following form:

ExternalDataCallResponse¶

{
  // Optional
  fieldValues : map<string,[string]>
}

Example¶

An auto insurer wants to use the VIN number to get accurate vehicle information from the US Department of Transportation, which makes it available via a public web service.

In this example, The user can enter the VIN number and system will automatically populate the vehicle’s make, model, and year. This will work whether the data input is via Socotra’s UI or API.

Web service wrapper:¶

def process_vin(vin_input):
  return_value = {}
  fields = {}

  # Make request call to NHTSA database
  url = 'https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVINValuesBatch/'
  post_fields = {'format': 'json', 'data': vin_input}
  r = requests.post(url, data=post_fields)
  vin_return = json.loads(r.text)

  # Check if there was a successful result
  if vin_return.get('Count') == 1:
    car = vin_return['Results'][0]
    make = car['Make']
    model = car['Model']
    model_year = car['ModelYear']

    # Construct external return value
    fields['make'] = [make]
    fields['model'] = [model]
    fields['model_year'] = [model_year]
    return_value['fieldValues'] = fields

  return return_value

Complete exposure.json file:¶

{
"fields": [
    {
      "name": "vin",
      "title": "VIN",
      "type": "string"
    },
    {
      "name": "make",
      "title": "Make",
      "type": "string"
    },
    {
      "name": "model",
      "title": "Model",
      "type": "string"
    },
    {
      "name": "model_year",
      "title": "Year",
      "type": "string"
    }
  ],
"externalDataCalls": [
    {
    "triggerField": "vin",
    "targetFields": ["make", "model", "model_year"],
    "uri": "https://www.acmeinsure.com/socotra/nhtsa"
    }
  ]
}