Getting Started with the Socotra API

This guide describes how to interact with the Socotra API and demonstrates how it is used.

The Socotra API is a REST API that supports HTTP and JSON - it provides a programmatic approach to build on top of the Socotra platform. All Socotra operations, including retrieving, creating, and manipulating data, are available via a set of HTTP endpoints. Unless otherwise noted, all requests take JSON data as input and return a JSON response.

Socotra also offers a swagger file for using other tools with the Socotra API.

Important

The API documentation refers to some return fields as having type timestamp. Those represent the number of milliseconds since the UNIX epoch, encoded as strings.

Tip

Contact Socotra support (support@socotra.com) if you need any assistance.

What You Need

You’ll need an account on Socotra Configuration Studio, Socotra’s development server. Contact Socotra support (support@socotra.com) if you do not have one. We expect that the reader has basic programming experience. (Sample HTTP requests and the example code here are provided in Python.)

The scripts below are based on the default configuration in Configuration Studio.

URLs

Base URL

The base URL is the prefix for all URLs when using the Socotra API. For testing and development, the base URL is https://api.sandbox.socotra.com. This is the prefix for all API interactions in this guide and all endpoints in the API documentation.

Sandbox URL

The sandbox URL is where your Socotra instance lives. It is constructed using your Configuration Studio account username, for example: https://my_user_name-configeditor.co.sandbox.socotra.com.

Authentication and Authorization

Authentication

The Socotra API uses token-based authentication. For testing, your API client obtains an authorization token using a username and password configured in the security/test_users.json file.

Note

The username/password you use to obtain an authorization token are not the same as your Configuration Studio credentials.

The code is provided in Python but is easily adaptable to the language of your choice. Many of us use Requests, an HTTP library for Python, which you can install via python -m pip install requests, if you don’t have it already.

Authentication Request:

import requests

response = requests.post(
    'https://api.sandbox.socotra.com/account/authenticate',
    json = { 'hostName':'<username>-configeditor.co.sandbox.socotra.com',
             'username':'alice.lee',
             'password':'socotra'})

Authentication Response:

{
    "authorizationToken": "eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50LnR5cGUiOiJhY2NvdW50L",
    "expiresTimestamp": "1589740898000"
}

See also

Authentication by hostname endpoint

Authorization

The authorization token from authentication can then be used for subsequent requests. Below we use the authorization token to create a policyholder:

response = requests.post(
    'https://api.sandbox.socotra.com/policyholder/create',
    headers = {'Authorization':'eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50LnR5cGUiOiJhY2NvdW50L'},
    json = {'values': {'first_name':'John', 'last_name':'Smith'}})

Typical Fields

We describe in the following table a few system and user defined object attributes commonly found in the HTTP requests and responses.

Name

Type

Example

Description

timestamp

string

“1589740898000”

Unix time stamps, i.e., the number of milliseconds between a particular date and the Unix Epoch. Timestamps are included in most Socotra system responses.

locator

string

“bd6b75a5-befc-440a-ae3d-a3fe2fb82388”

32-digit hexadecimal unique object identifier stored as a string. Locators are indexed, which means you can search for them in the search bar.

human readable IDs / display IDs

string

“104677234”

Unique object reference stored as a string. Socotra auto-generates 9-digit integers by default but the number of digits is configurable. Similar to locators, human readable IDs are indexed.

date

string

“1978-02-17”

Dates are in YYYY-MM-DD format. Socotra uses ISO 8601

datetime

string

“2015-01-08T20:48:28+00:00”

Date and time use the <date>T<time> format also according to the ISO 8601 standard

number

string

“92233.07”

To avoid floating point errors and other typing issues, Socotra sends all numbers as strings in responses.

Field Value Maps

Field values map string-based keys to JSON object arrays. For example:

{
    "fieldValues": {
        "first_name": ["John"],
        "last_name": ["Smith"],
        "date_of_birth": ["1987-10-03"],
        "channel": ["Direct"]
    }
}

Here we show the map fieldValues, and corresponding JSON object. The object keys come from the dictionary in the associated Socotra sandbox system; their corresponding values should match the specified format.

Note

The value associated with each key is generally an array type, to handle cases where multiple values are associated with a key, such as for a select type. For most common purposes you can just use the first element, such as first_name[0].

When sending requests to Socotra, the value can be either an array or a single value if only one value will be associated with a key. For example, the above json object could have been sent as:

{
    "fieldValues": {
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1987-10-03",
        "channel": "Direct"
    }
}

Errors and Exceptions

See the Errors and Exceptions API guide for details about error messages returned from the Socotra API.

Example: Creating a Policy

This example will provide a starting point for future API exploration. This example has four steps:

  • Get an authorization token

  • Create a policyholder

  • Create an exposure

  • Create a policy with that exposure

  • Print policy information

We explain each step below.

Get an Authorization Token

As mentioned earlier, every request to an API endpoint (excluding authentication endpoints) requires an authorization token. In this step we obtain an authorization token and store it for future requests. Let’s get started writing some code:

import requests
import argparse


def get_hostname():
    parser = argparse.ArgumentParser()
    parser.add_argument('hostname')
    args = parser.parse_args()
    return args.hostname

def create_session_and_login(hostname):
    # Login as a employee of your tenant
    username = 'alice.lee'
    password = 'socotra'

    # Create a session with Socotra
    session = requests.Session()
    response = session.post(
        'https://api.sandbox.socotra.com/account/authenticate',
        json={'username': username,
              'password': password,
              'hostName': hostname})

    # Save the authorization token for use in future requests
    authorization_token = response.json()['authorizationToken']
    session.headers.update({'Authorization': authorization_token})
    return session

def main():
    hostname = get_hostname()
    session = create_session_and_login(hostname)

if __name__ == '__main__':
    main()

Create a Policyholder

Next, we’ll create a policyholder using the token we obtained in the previous step. A policyholder represents a customer in Socotra and so is a good place to start. The following function creates a policyholder:

def create_policyholder(session):
    # Create a Policyholder
    policyholder_values = {'first_name': 'John',
                            'last_name': 'Smith',
                            'date_of_birth': '1987-10-03',
                            'policyholder_id': 'placeholder'}
    response = session.post(
        'https://api.sandbox.socotra.com/policyholder/create',
        json={'values': policyholder_values})
    return response.json()

Add the create_policyholder function to main:

def main():
    hostname = get_hostname()
    session = create_session_and_login(hostname)
    policyholder_information = create_policyholder(session)

Create an Exposure

Now that we have a customer, we want to create an insurance policy. In Socotra, a policy insures an exposure (ie. a vehicle) which can be covered for one or more perils (i.e. bodily injury or third-party liability).

This is based on the defined exposures and perils that are configured in your sandbox. Let’s define a vehicle to be applied to a policy.

def create_exposure():
    # Create an exposure with two perils
    exposure_values = {
      'vehicle_type': 'Car',
      'make': 'Audi',
      'model': 'A4',
      'year': '2012',
      'vehicle_value': '123',
      'license_plate': '123456',
    }

    exposure = {
      'exposureName': 'vehicle',
      'fieldValues': exposure_values,
      'perils': [{'name': 'bodily_injury'},
                 {'name': 'third_party_liability'}]
    }

    return exposure

Create a Policy

Now that we have a customer, we want to create an insurance policy. Again, this is based on the insurance products available in the sandbox, as well as the required policyholder information from the previous step. Let’s create an automobile policy for John Smith:

def create_policy(session, policyholder_information):
    # Create a policy using the exposure referenced above
    policyholder_locator = policyholder_information['locator']

    policy_values = {'channel': 'Direct'}
    exposures = [create_exposure()]

    policy = {
        "policyholderLocator": policyholder_locator,
        "productName": 'simple_auto',
        "fieldValues": policy_values,
        "exposures": exposures
    }

    response = session.post('https://api.sandbox.socotra.com/policy',
                            json=policy)

    policy_information = response.json()
    return policy_information

And then add the create_policy call to the main function:

def main():
  hostname = get_hostname()
  session = create_session_and_login(hostname)
  policyholder_information = create_policyholder(session)
  policy_information = create_policy(session, policyholder_information)