Prior policies

Every policy and job has a set of risk analysis information. The insurer can use this information to determine how to process policy transactions. For example, this information could be used to determine whether or not to renew a policy.

One category of risk information is the prior policies. Prior policies is a list of policies that the insured has held before the current policy. These could be policies with the insurer or with other insurers. For more information on the business functionality of prior policies, see the Application Guide.

You can retrieve and manage prior policy information through Cloud API.

Prior policies in PolicyCenter

Prior policy information is stored in the PriorPolicy data model entity. Every entity has an array of PriorPolicies. The fields in the PriorPolicy data model entity that are exposed in the user interface include the following:

  • AnnualPremium
  • Carrier
  • EffectiveDate
  • ExpirationDate
  • NumLosses
  • PolicyNumber
  • TotalLosses (a monetary amount)

In the base configuration, prior policy information appears in the following places:

  • Within the relevant Job wizards (such as submission and policy change), on the Risk Analysis step's Prior Policies tab
  • On the policy's Risk Analysis screen's Prior Policies tab

In the base configuration:

  • You can view prior policy information in either location.
  • You can edit prior policy information only in a Job wizard. (In other words, you cannot edit prior policy information outside of the context of a job.)

Prior policies in Cloud API

Prior policy information is tracked in the PriorPolicy resource.

Through Cloud API:

  • You can view prior policy information on a job or a policy.
  • For policies not yet bound, you can edit prior policy information on the submission job.
  • For bound policies, you can edit prior policy information on the policy itself.

Querying for prior policy information

Use the following endpoints to query for prior policy information:

  • Jobs
    • GET /job/v1/jobs/{jobId}/prior-policies
    • GET /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
  • Policies
    • GET /policy/v1/policies/{policyId}/prior-policies
    • GET /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}
For example, the following query retrieves the prior policy information for job pc:334.
GET /job/v1/jobs/pc:334/prior-policies

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "annualPremium": {
                    "amount": "5092.00",
                    "currency": "usd"
                },
                "carrier": "CommuteCoverage",
                "effectiveDate": "2021-09-04",
                "id": "pc:SlpveONavkeunmUPCU4nZ",
                "numLosses": 1,
                "policyNumber": "CO-43221-3",
                "totalLosses": {
                    "amount": "5721.13",
                    "currency": "usd"
                }
            },
            ...

Creating prior policy information

Use the following endpoints to create prior policy information:

  • POST /job/v1/jobs/{jobId}/prior-policies
  • POST /policy/v1/policies/{policyId}/prior-policies

Minimum creation criteria

The only field required to create a PriorPolicy is effectiveDate.

POST example

The following payload creates a PriorPolicy for job pc:334. Note that it includes the required field (effectiveDate) and additional optional fields.

POST /job/v1/jobs/pc:334/prior-policies

{
  "data": {
    "attributes": {
        "carrier": "Interstate Insurance",
        "effectiveDate": "2021-10-13",
        "annualPremium": {
            "amount": "617.00",
            "currency": "usd"
        },
        "policyNumber": "BNL-123312-2"
    }
  }
}

Updating prior policy information

PATCHing prior policy information

Use the following endpoints to PATCH prior policy information:

  • PATCH /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
  • PATCH /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}

For example, the following payload modifies prior policy pc:1119 for job pc:334.

PATCH /job/v1/jobs/pc:334/prior-policies/pc:1119

{
  "data": {
    "attributes": {
      "numLosses": 0,
      "totalLosses": {
        "amount": "0.00",
        "currency": "usd"
      }
    }
  }
}

DELETEing prior policy information

Use the following endpoints to DELETE prior policy information:

  • DELETE /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
  • DELETE /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}

For example, the following payload deletes prior policy pc:1119 from job pc:334.

DELETE /job/v1/jobs/pc:334/prior-policies/pc:1119

<no request payload>