To create a policy, you will need to hit the POST /policys endpoint with a policy object. A policy object is a detailed JSON payload with all the elements necessary to cover the full scope of risk for policy management and reporting.

Policy object

An example policy object is shown below.

{
    "policy": {
        "compulsory_excess": 100,
        "voluntary_excess": 100,
        "address": {
            "line_1": "Flat 1, 11 The Street",
            "line_2": "Little Hampton",
            "line_3": "Burton-on-the-water",
            "county": "Avon",
            "city": "Stroud",
            "country": "GB",
            "postcode": "W53TR"
        },
        "usage": "SDP",
        "cover": "Comprehensive",
        "auto_renew": true,
        "start_date": 1599567165,
        "end_date": 1599567165,
        "billing_day_date": 21,
        "underwriter_reference": "zurich",
        "underwriter_policy_reference": "AXABM000001",
        "product_reference": "pay-by-mile",
        "created_at": 1599567165,
        "policy_reference": "apple-orange-pear"
    },
    "proposer": {
        "title": "003",
        "first_names": "Dave",
        "last_names": "Jones",
        "email": "dave@jones.com",
        "phone_number": "+447999000011",
        "children": 1,
        "has_medical_conditions": true,
        "has_informed_dvla_medical_conditions": false,
        "ncd": 1,
        "dob": "1980-12-31",
        "licence_type": "F",
        "employment": "E",
        "occupation": "51D",
        "business": "077",
        "licence_issued_date": "2000-12-31",
        "residency_date": "2000-12-31",
        "has_criminal_conviction": false,
        "convictions": [
            {
                "code": "AC10",
                "date": "2018-01-01",
                "points": 3,
                "ban": 0
            }
        ],
        "claims": [
            {
                "code": "A",
                "date": "2016-01-01",
                "at_fault": false,
                "ncd_lost": false
            }
        ],
        "own_home": false
    },
    "vehicle": {
        "reg": "WO123XX",
        "vin": "YV1UZ25UCK1337428",
        "type": "01",
        "make": "Tesla",
        "model": "S",
        "colour": "black",
        "rating": 21,
        "group_rating_50": 21,
        "group_rating_20": 10,
        "abi_code": "01001000",
        "engine": 1650,
        "fuel": "001",
        "owner": "1",
        "keeper": "1",
        "estimated_yearly_mileage": 10000,
        "purchase_date": "2016-01-01",
        "manufacture_date": "2016-01-01",
        "current_value": 1000,
        "is_rhd": true,
        "seats": 5,
        "doors": 3,
        "is_parked_home": true,
        "is_import": true,
        "overnight_postcode": "SW1 5BB",
        "parked_location": "Garage"
    },
    "additional_drivers": [
        {
            "relationship": "P",
            "title": "003",
            "first_names": "Dave",
            "last_names": "Jones",
            "email": "dave@jones.com",
            "phone_number": "+447999000011",
            "children": 1,
            "has_medical_conditions": true,
            "has_informed_dvla_medical_conditions": false,
            "ncd": 1,
            "dob": "1980-12-31",
            "licence_type": "F",
            "employment": "E",
            "occupation": "51D",
            "business": "077",
            "licence_issued_date": "2000-12-31",
            "residency_date": "2000-12-31",
            "has_criminal_conviction": false,
            "convictions": [
                {
                    "code": "AC10",
                    "date": "2018-01-01",
                    "points": 3,
                    "ban": 0
                }
            ],
            "claims": [
                {
                    "code": "A",
                    "date": "2016-01-01",
                    "at_fault": false,
                    "ncd_lost": false
                }
            ],
            "own_home": false
        }
    ],
    "pricing": {
        "upfront_rate": 100,
        "subscription_rate": 20,
        "usage_rate": 0.04,
        "subscription_installments": 12,
        "quote_reference": "36c575d2-b6b9-44ed-9c75-3d705b987ec1",
        "quote_version_reference": "46c575d2-b6b9-44ed-9c75-4d705b987ec1",
        "withhold_fee": 50,
        "deposit_fee": 50,
        "admin_fee": 60,
        "mta_fee": 20,
        "cancel_fee": 50,
        "ipt_rate": 12,
        "commission_rate": 15
    },
    "custom": {}
}

The main parts of the policy object are:

  • policy - Details about the policy in general. e.g. start date, excess etc.
  • proposer - Details about the main driver on cover
  • vehicle - Details about the vehicle on cover
  • additional_drivers - An array of other named drivers on cover
  • pricing - The premium price of the policy (normally generated by the quoting engine)
  • custom - A custom key/value store that can take up to 25 items

Create a policy

// Example Request
{
    "url": "https://api.bybits.co.uk/policys",
    "headers": {
        "client_secret": "11111-22222-33333-44444",
        "client_id": "11111-22222-33333-44444",
        "environment": "production"
    },
    "method": "POST",
    "data: <policy_object>
}

If the policy object details are incomplete or malformed, an error message will be reported back with a status code of 422.

If the policy object is valid, then a new policy will be created with a version type of nb (i.e. New Business). This policy will also have a public policy reference created.

// Example Response
{
    ...<policy_object>,
    "policy_reference": "watch-novel-miami",
    "policy_version_reference": "1fb4c609-f6c6-4c65-bef0-579d483a6ea2",
    "versions": [{
      "version_type": "nb",
      "policy_reference": "watch-novel-miami",
      "policy_version_reference": "1fb4c609-f6c6-4c65-bef0-579d483a6ea2",
      "usage": "SDP",
      "email": "anymail@bybits.co.uk",
      "vehicle_reg": "WO123XX",
      "address_postcode": "W68DJ",
      "inception_date": "2019-06-14T23:00:00.000Z",
      "effective_date": "2019-06-14T23:00:00.000Z",
      "start_date": "2019-06-14T23:00:00.000Z",
      "end_date": "2020-06-14T23:00:00.000Z",
      "upfront_rate": 100,
      "subscription_rate": 20,
      "usage_rate": 0.01,
      "upfront_premium": 100,
      "subscription_premium": 20,
      "usage_premium": 0,
      "ipt_rate": 0,
      "commission_rate": 0
    }]
}

Each change to a policy will create a new policy version with its own UUID reference. A new version will be created with every adjustment (mta), usage statement (st), cancellation (cn), renewal (rn) and lapse (ls).

Policyholder authentication

Policy creation will automatically generate a user account for the policyholder. An email will automatically be sent to the email address defined in the policy object. A temporary password and username will be generated and the documented authentication flow will be initiated.