External Data Calls

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


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.


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


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


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


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"



Valid Values




field name

Changing this field triggers the external data call



array of field names

The fields to be populated with the response



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:


exposureCharacteristics ExposureCharacteristicsResponse
perilCharacteristics PerilCharacteristicsResponse
policyCharacteristics PolicyCharacteristicsResponse


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:

fieldValues map<string,[string]>


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"