Policy Management

This page provides supplementary information for the Policy Management API.

Get policy details

Send a request that looks like below to retrieve details of a single policy. Please replace the :id path variable with the actual policy Id.

### Get details of a single policy
GET {{base-url-underwriting}}/api/v1/policies/:id?fields[policies]=reference,description,period,status,currencyCode
Authorization: {{access-token}}
Accept: application/vnd.api+json

Sample response

HTTP/2 200 OK
{
  "data": {
    "type": "policies",
    "id": "policy-6f21f713-f977-5ded-a1d0-15d82ee48931",
    "attributes": {
      "reference": "1106467",
      "description": "Sample Customer Name",
      "period": {
        "start": "2024-12-19T00:00:00+00:00",
        "end": "2025-12-18T23:59:59+00:00"
      },
      "currencyCode": "GBP",
      "status": "Created"
    }
  }
}

Get policies belonging to a customer

To get policies belonging to a customer, send a request with parameters for paging, sorting, filtering, and a sparse fieldset selection. Please replace the {{policy-holder-id}} query parameter with the actual policy holder Id (aka the customer Id). For example,

### Get policies belonging to a customer
GET {{base-url-underwriting}}/api/v1/policies?sort=-createdDate&fields[policies]=reference,description,period,status,currencyCode&page[size]=10&page[number]=1&filter[policyHolderId]={{policy-holder-id}}
Authorization: {{access-token}}
Accept: application/vnd.api+json

Sample response

HTTP/2 200 OK
{
  "data": [
    {
      "type": "policies",
      "id": "policy-6f21f713-f977-5ded-a1d0-15d82ee48931",
      "attributes": {
        "reference": "1106467",
        "description": "Sample Customer Name",
        "period": {
          "start": "2024-12-19T00:00:00+00:00",
          "end": "2025-12-18T23:59:59+00:00"
        },
        "currencyCode": "GBP",
        "status": "Created"
      }
    },
    ...
  ],
  "meta": {
    "total-records": 3,
    "totalResources": 3
  }
}

Create a new policy directly

For scenarios where quotation process is not necessary, the system allows creating the policy directly.

Please note to update "organizationContext": "<tenant or organization ID>" value.

The system expects "sourceId": "external-sale-1305" to be unique and repeating the same value will stop the policy from being created.

POST {{base-url-underwriting}}/api/v1/policies/createPolicyRequest
Authorization: {{access-token}}
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "createPolicyRequests",
    "attributes": {
      "policyReference": "5500002",
      "sourceId": "external-sale-1305",
      "sourceSystemReference": "partner-B",      
      "period": {
        "start": "2025-03-05T00:00:00.000Z",
        "end": "2026-03-04T00:00:00.000Z",
        "insurancePeriodStrategy": ""
      },
      "insuredObjectReference": "John Doe",
      "answers": {
        "InsuredFirstNameTag": "John",
        "InsuredLastNameTag": "Doe",
        "InsuredDOBTag": "1985-05-12",
        "RateByAgeTag": "Standard",
        "OccupationTag": "Engineer",
        "IndexTag": "1",
        "LifeSumInsuredTag": "100000",
        "DisabilityCoverTag": "Yes",
        "DisabilityInsuredTag": "50000",
        "BasePremiumTag": "200"
      },
      "currencyCode": "SEK",
      "proratablePremium": {
        "prorataType": "Annual365Premium",
        "premiumBeforeProRata": {
          "coverBreakdown": [
            {
              "identity": {
                "id": 5001,
                "name": "Death",
                "industryCode": "",
                "reportingCode": ""
              },
              "price": {
                "totalValue": {
                  "amount": 100,
                  "unroundedAmount": 100,
                  "roundingStrategy": "RoundAwayFromZeroTo2DecimalPlaces"
                },
                "preciseTotal": {
                  "amount": 100,
                  "unroundedAmount": 100,
                  "roundingStrategy": "NoRounding"
                },
                "breakdown": {
                  "tariffPremium": {
                    "amount": 100,
                    "unroundedAmount": 100,
                    "roundingStrategy": "RoundAwayFromZeroTo2DecimalPlaces"
                  },
                  "underwritingAdjustment": {
                    "amount": 0,
                    "unroundedAmount": 0,
                    "roundingStrategy": "RoundAwayFromZeroTo2DecimalPlaces"
                  },
                  "salesDiscount": {
                    "amount": 0,
                    "unroundedAmount": 0,
                    "roundingStrategy": "RoundAwayFromZeroTo2DecimalPlaces"
                  },
                  "taxComponents": {},
                  "additionalComponents": {},
                  "reportingItems": {}
                }
              }
            }
          ]
        }
      },
      "sourceSalesChannel": "saleschannel-10201c2f-4f32-08dd-391d-e1d818744bc2",
      "salesChannelName": "BOP sales channel",
      "salesChannelReference": "1",
      "productVersionId": "productversion-6f929ad3-4f37-08dd-3a7b-612cea438dca",
      "productName": "Accident",
      "productId": "product-76b922cb-4f31-08dd-b1b7-fbaf54bb39cd",
      "templateId": "string",
      "policyHolderId": "7411b977-203c-44c3-bf3f-3520af5a571b",
      "policyHolderData": {
        "id": "7411b977-203c-44c3-bf3f-3520af5a571b",
        "name": "John Test",
        "organizationContext": "<tenant or organization ID>"
      },
      "salesDiscount": 0,
      "productCommission": 0,
      "underwritingAdjustment": 0,
      "underwritingAdjustmentReason": null,
      "salesCommission": 0,
      "paymentMethod": "invoice",
      "paymentFrequency": "monthly"
    }
  }
}

Terminate a policy

The policy termination flow starts with a call to calculate the policy termination

### Step 1: POST /calculateTerminationRequest
POST {{base-url-underwriting}}/api/v1/policies/calculateTerminationRequest
Authorization: {{access-token}}
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "calculateTerminationRequests",
    "attributes": {
      "policyId": "policy-7e578db3-f471-56ff-abec-22965a7f03fc",
      "acknowledgedExistenceOfClaims": false
    }
  }
}

The API records the termination request and returns the policy data similar to the truncated sample below

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "policies",
    "id": "policy-7e578db3-f471-56ff-abec-22965a7f03fc",
    "attributes": {
      "reference": "500000",
      "period": {
        "start": "2025-05-01T00:00:00+00:00",
        "end": "2026-04-30T23:59:59+00:00"
      },
      "status": "Activated",
      ...
    }
    ...
  }
  ...
}

The client app then sends another /calculateTerminationRequest request with more details, e.g. effectiveFrom, selectedReason, etc.

### Step 2: POST /calculateTerminationRequest with effective date and reason
POST {{base-url-underwriting}}/api/v1/policies/calculateTerminationRequest
Authorization: {{access-token}}
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "calculateTerminationRequests",
    "attributes": {
      "policyId": "policy-7e578db3-f471-56ff-abec-22965a7f03fc",
      "effectiveFrom": "2025-07-01",
      "selectedReason": "NOT_NEEDED",
      "terminationFee": 0,
      "terminationEmailRequired": false,
      "terminationEmailTemplateId": "",
      "acknowledgedExistenceOfClaims": true
    }
  }
}

Sample response includes the premiumAfterTermination.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "policies",
    "id": "policy-7e578db3-f471-56ff-abec-22965a7f03fc",
    "attributes": {
      "reference": "500000",
      "status": "Activated",
      "terminationRequest": {
        "effectiveDate": "2025-07-01T00:00:00+07:00",
        "selectedReasonCode": "NOT_NEEDED",
        "premiumAfterTermination": {
          "amount": 105.13,
          "currencyCode": "GBP",
          "formattedAmount": "105.13 GBP"
        }
        ...
    }
    ...
  }
  ...
}

Finally, the app client can call terminatePolicyRequest to complete the termination flow.

### Step 3: POST /terminatePolicyRequest
POST {{base-url-underwriting}}/api/v1/policies/terminatePolicyRequest
Authorization: {{access-token}}
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
  "data": {
    "type": "terminatePolicyRequests",
    "attributes": {
      "policyId": "policy-7e578db3-f471-56ff-abec-22965a7f03fc"
    }
  }
}

Sample response with policy status changed:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "type": "policies",
    "id": "policy-7e578db3-f471-56ff-abec-22965a7f03fc",
    "attributes": {
      "reference": "500000",
      "status": "PendingTermination",
      "terminationRequest": {
        "effectiveDate": "2025-07-01T00:00:00+07:00",
        "selectedReasonCode": "NOT_NEEDED",
        "premiumAfterTermination": {
          "amount": 105.13,
          "currencyCode": "GBP",
          "formattedAmount": "105.13 GBP"
        }
        ...
    }
    ...
  }
  ...
}