Loss history

Loss history: Attached

The LossHistoryType field can be set to Attached (code att). This indicates that information about prior losses is defined in a set of attached documents. In addition to those documents, information about the loss history is summarized in the following Policy fields:

• NumPriorLosses - The number of prior losses. (In the user interface, this is specified as the number of prior losses in the past 5 years, but there is no enforcement of time span in the database.)
• PriorTotalIncurred - The total amount of the prior losses.

The documents that define the prior losses are associated with the policy in the same way as any other document. There is no array specifically for loss history documents. However, all documents that pertain to loss history have a document type of loss_history.

Loss history: Manually entered

The LossHistoryType field can be set to Manually entered (code man). This indicates that information about prior losses is defined in a set of loss history entries whose contents are manually entered by an underwriter.

Information about the loss history is captured in the Policy entity's PriorLosses array. Each member is an instance of the LossHistoryEntry entity, which has the following fields:

• AmountPaid
• AmountResv (the amount of any open reserve)
• Description
• LossStatus
• OccurenceDate
• TotalIncurred

Loss history: No Loss History

The LossHistoryType field defaults to No loss history (code nol). This indicates that there have been no prior losses. You can also manually set the LossHistoryType field to No loss history.

Loss history in the user interface

In the base configuration, loss history information appears in the following places:

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

In the base configuration:

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

Differences between the user interface and Cloud API

The user interface does not permit the creation or change of loss history information outside of the context of a job. However, Cloud API has endpoints that can create and modify loss history information directly on policies, outside of the context of a job.

Retrieving loss history type

To determine a policy's loss history type, use the following endpoints:

• GET /job/v1/jobs/{job-id}/loss-history
• GET /policy/v1/policies/{policy-id}/loss-history

For example, the following request retrieves the loss history type for job pc:333.

GET job/v1/jobs/pc:333/loss-history?fields=lossHistoryType

{
    "data": {
        "attributes": {
            "lossHistoryType": {
                "code": "man",
                "name": "Manually Entered"
            }
        },

Loss history: Attached

For policies with attached loss histories, use the following endpoints to get the number of losses and total incurred for the specified job or policy:

• GET /job/v1/jobs/{job-id}/loss-history
• GET /policy/v1/policies/{policy-id}/loss-history

For example, the following request retrieves the loss history information for job pc:444.

GET job/v1/jobs/pc:444/loss-history

{
    "data": {
        "attributes": {
            "lossHistoryType": {
                "code": "att",
                "name": "Attached"
            },
            "numPriorLosses": 2,
            "priorTotalIncurred": {
                "amount": "300.00",
                "currency": "usd"
            }
        },

There is no endpoint dedicated to retrieving the attached loss history documents. However, you can use the GET /documents endpoint to retrieve only the documents associated with the policy whose type is loss history.

For example, the following request retrieves the loss history documents for job pc:444.

GET job/v1/jobs/pc:444/documents?filter=type:eq:loss_history

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "id": "pc:S8SvBsGKtMsbxOfdw35lB",
                "name": "Loss Details - Accident on 2022/10/12",
                "status": {
                    "code": "draft",
                    "name": "Draft"
                },
                "type": {
                    "code": "loss_history",
                    "name": "Loss history"
                }
            },
            ...
        },
        {
            "attributes": {
                "id": "pc:Stac2g5QJvz2K96tyBkFp",
                "name": "Loss Details - Accident on 2020/07/08",
                "status": {
                    "code": "final",
                    "name": "Final"
                },
                "type": {
                    "code": "loss_history",
                    "name": "Loss history"
                }
            },
            ...
        }

Loss history: Manually entered

For policies with manually entered loss histories, use the following endpoints to get retrieve the loss history entry information for the specified job or policy:

• GET /job/v1/jobs/{job-id}/loss-history/prior-losses
• GET /job/v1/jobs/{job-id}/loss-history/prior-losses/{priorLossId}
• GET /policy/v1/policies/{policy-id}/loss-history/prior-losses
• GET /policy/v1/policies/{policy-id}/loss-history/prior-losses/{priorLossId}

For example, the following request retrieves the prior losses for job pc:555.

GET job/v1/jobs/pc:555/loss-history/prior-losses

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "amountPaid": {
                    "amount": "2000.00",
                    "currency": "usd"
                },
                "description": "Accident (with $500 deductible)",
                "id": "pc:Sgg81r2HeunCNnYYWSDvl",
                "lossStatus": {
                    "code": "Closed",
                    "name": "Closed"
                },
                "occurrenceDate": "2022-08-08",
                "openReserve": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "totalIncurred": {
                    "amount": "2500.00",
                    "currency": "usd"
                }
            },
            ...

Creating loss history entries

For a policy whose LossHistoryType field is set to Manually entered (code man), you can use the following endpoints to create a loss history entry:

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

When you create a loss history entry, there are no required fields. However, if you specify no fields, then the only field populated with a default value is id. This may result in a business object with limited value.

For example, the following payload creates a loss history entry for job pc:1221:

POST /job/v1/jobs/pc:1221/loss-history/prior-losses

{
  "data": {
    "attributes": {
        "amountPaid": {
            "amount": "2000.00",
            "currency": "usd"
         },
        "description": "Accident (with $500 deductible)",
        "lossStatus": {
            "code": "Closed"
        },
        "occurrenceDate": "2022-08-01",
        "openReserve": {
            "amount": "0.00",
            "currency": "usd"
        },
        "totalIncurred": {
            "amount": "2500.00",
            "currency": "usd"
        }
    }
  }
}

PATCHING loss history entries

Use the following endpoints to PATCH a loss history entry:

• PATCH /job/v1/jobs/{jobId}/loss-history/prior-losses/{priorLossId}
• PATCH /policy/v1/policies/{policyId}/loss-history/prior-losses/{priorLossId}

For example, the following payload PATCHes the occurrence date for loss history entry pc:99099 for job pc:1221:

PATCH /job/v1/jobs/pc:1221/loss-history/prior-losses/pc:99099

{
  "data": {
    "attributes": {
        "occurrenceDate": "2022-01-08"
    }
  }
}

DELETEing loss history entries

Use the following endpoints to DELETE a loss history entry:

• DELETE /job/v1/jobs/{jobId}/loss-history/prior-losses/{priorLossId}
• DELETE /policy/v1/policies/{policyId}/loss-history/prior-losses/{priorLossId}

For example, the following payload deletes loss history entry pc:99099 from job pc:1221:

DELETE /job/v1/jobs/pc:1221/loss-history/prior-losses/pc:99099

<no request body>