External Data Calls

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

Warning

External Data Calls are deprecated and will be removed in a future release. Socotra recommends the use of Data Auto-Fill as a better alternative.

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 health information to 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 relevant 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 PolicyResponse

optional
exposureCharacteristics ExposureCharacteristicsResponse
perilCharacteristics PerilCharacteristicsResponse
policyCharacteristics PolicyCharacteristicsResponse

Warning

When the external data call is being made, it is not allowed to call back and update the affected policy via the Socotra API. Wait until the transaction that triggered the external data call to complete before making such as update.

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"
    }
  ]
}