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¶
{// Requiredpolicy : Policy2Response// OptionalexposureCharacteristics : ExposureCharacteristicsResponseperilCharacteristics : PerilCharacteristicsResponsepolicyCharacteristics : PolicyCharacteristicsResponse}
ExternalDataCallResponse¶
{// OptionalfieldValues : 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" } ] }