Overview of incidents and risk units

Incidents

An incident is a collection of information about an item that was lost or damaged, such as:

  • A vehicle
  • A piece of baggage
  • A trip that was canceled shortly before commencing

For example, a vehicle incident can store the following information:

  • Where was the point of collision?
  • Who was the driver?
  • What is the severity of the damage?

Incident is a subtyped entity. Cloud API provides endpoints for the Incident supertype and most of its subtypes. For more information, see the Cloud API Consumer Guide.

There are typically five endpoints for every type of incident: a collection GET, an element GET, a POST, a PATCH, and a DELETE. For example, baggage incidents have the following endpoints:

  • GET /claim/v1/claims/{claimId}/baggage-incidents
  • POST /claim/v1/claims/{claimId}/baggage-incidents
  • GET /claim/v1/claims/{claimId}/baggage-incidents/{incidentId}
  • PATCH /claim/v1/claims/{claimId}/baggage-incidents/{incidentId}
  • DELETE /claim/v1/claims/{claimId}/baggage-incidents/{incidentId}

Assessment content items

Custom incidents can make use of assessment content items. An assessment content item is an individual item covered by the policy. Assessment content items are useful when you want to cover some large container object (such as a house), but you also want to track the contents of the container individual (such as tracking each piece of fine jewelry in a house).

For example, in the base configuration, a baggage incident is a "container object" that captures loss information about a piece of baggage that was lost or damaged during a covered trip. The policy may also cover individual items within the baggage. If they do, each covered item within the baggage is an assessment content item.

There are typically five endpoints for an incident's assessment content items: a collection GET, an element GET, a POST, a PATCH, and a DELETE. These endpoints are child endpoints with a specific incident as the parent. For example, assessment content items for baggage incidents have the following endpoints:

  • GET /claim/v1/claims/{claimId}/baggageincidents/{incidentId}/assessment-content-items
  • POST /claim/v1/claims/{claimId}/baggageincidents/{incidentId}/assessment-content-items
  • GET /claim/v1/claims/{claimId}/baggageincidents/{incidentId}/assessment-contentitems/{assessmentContentItemId}
  • PATCH /claim/v1/claims/{claimId}/baggageincidents/{incidentId}/assessment-contentitems/{assessmentContentItemId}
  • DELETE /claim/v1/claims/{claimId}/baggageincidents/{incidentId}/assessment-contentitems/{assessmentContentItemId}

Additional accessible fields filters

Incidents can store information about third parties. For example, a claim that involves a collision with another driver will have incident information about the third-party driver's vehicle. Third-party information ought to be accessible to some types of caller, such as claims adjusters. But it ought to be inaccessible to other types of callers, such as producers.

In these situations, the fields a caller can access is not an "all or nothing" decision, but rather a "all or limited set only" decision. Furthermore, the choice of "all fields" or "a limited set of fields only" depends on the business relationship that the caller has with the data. This type of restriction is implemented through an "additional accessible fields filter". An additional accessible fields filter is an expression that evaluates the business relationship the caller has with a given resource. This evaluation may add restrictions that limit the caller to a specific subset of fields.

When you create a custom incident type, the REST endpoint generator automatically creates some additional accessible fields filter logic. However, this information is incomplete. For each custom incident type, you must do one of the following:

  • If the incident stores third-party information that is accessible only for callers with a specific business relationship, you must complete the configuration started by the REST endpoint generator.
  • If the incident does not store any third-party information that is accessible only for callers with a specific business relationship, you must remove the configuration added by the REST endpoint generator.

For information on how to remove or complete the configuration, see one of the following:

For more information on additional accessible fields filters in general, see Resource access files: additional accessible fields filters.

Risk units

A risk unit is a policy descendant that identifies a thing covered on a policy. For example, a Personal Auto policy may have one or more VehicleRU risk units. A Travel policy may have one or more TripRU risk units.

Verified and unverified policy endpoints

A verified policy is a policy that is based on information retrieved from the PAS. In a production system, verified policies are the most common types of policies.

An unverified policy is a policy that is created during the FNOL process based on information supplied by an adjuster or by the caller application. This information may or may not correctly correspond to information in a PAS. Unverified policies let adjusters start the FNOL process without information from the PAS. This could be necessary if the reporter does not know or cannot recall enough information to find the policy.

For every type of policy descendant, Cloud API provides two endpoints: one for verified policies and one for unverified policies.

For a verified policy:

  • The policy descendant endpoints start with /claim/v1/claims/{claimId}/policy.
  • The only supported method is GET. (You can edit information on a verified policy, but this converts the policy to an unverified policy. As of this release, Cloud API does not support this type of action.)

For an unverified policy:

  • The policy descendant endpoints start with /claim/v1/unverified-policy.
  • The GET, POST, and PATCH operations are supported. (As of this release, Cloud API does not support the DELETE method for unverified policy descendants.)

For example, the following are the endpoints for vehicle risk units:

  • Verified policies
    • GET /claim/v1/claims/{claimId}/policy/vehicle-risk-units
    • GET /claim/v1/claims/{claimId}/policy/vehicle-risk-units/{vehicleRiskUnitId}
  • Unverified policies
    • GET /claim/v1/unverified-policies/{policyId}/vehicle-risk-units
    • GET /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}
    • POST /claim/v1/unverified-policies/{policyId}/vehicle-risk-units
    • PATCH /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}

Risk units and coverages

Policies have two types of coverages. A policy-level coverage is attached to the policy itself and typically consists of liability coverages that protect the policy holder (and other named insureds). Policy-level coverages are managed using a /coverages endpoint whose parent is either /policy or /unverified-policy/{policyId}. For example:

  • GET /claim/v1/claims/{claimId}/policy/coverages
  • GET /claim/v1/unverified-policies/{policyId}/coverages

A risk unit coverage is attached to a specific risk unit and provides coverage for that risk unit only. For example, Collision Coverage is typically attached to a specific VehicleRU and covers damage due to collision for that VehicleRU only. Risk unit coverages are managed using a /coverages endpoint whose parent is a specific risk unit. For example:

  • GET /claim/v1/claims/{claimId}/policy/vehicle-risk-units/{vehicleRiskUnitId}/coverages
  • GET /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}/coverages

Damageables

Within the context of risk units and incidents, a damageable is a separate entity that stores information about the state of a covered item before any loss or damage occurred. For example, Vehicle is a damageable. It stores information about the vehicle about the covered vehicle itself as covered on the policy, such as Make, Model, and LicensePlate.

Inline damageables

When a risk unit or incident has an associated damageable, Cloud API does not have separate endpoints for both the risk unit and the damageable. Instead, the damageable is added to the incident schema and risk unit schema as an inline object. All manipulation of the damageable occurs through the incident or risk unit endpoints. Thus, a damageable can also be referred to as inline damageable.

For example, in the base configuration data model, there is a VehicleIncident entity and a Vehicle entity. In Cloud API, there are no endpoints for Vehicle. Instead, Vehicle is managed as an inline damageable in the VehicleIncident schema. The following is a portion of a VehicleIncident payload with the inline Vehicle.

{
  "data": {
    "attributes": {
      "collisionPoint": {
        "code": "front",
        "name": "Front"
      },
      "damageDescription": "Damage to front left fender, body, and frame.",
      "id": "cc:SJm9n7N1j3-1Ec9mG1Dh5",
      "severity": {
        "code": "minor",
        "name": "Minor"
      },
      "vehicle": {
        "displayName": "1997 Saturn SL (1HGJ465 / California)",
        "id": "cc:SY-oUPhtyUT0KR2FQYOxL",
        "licensePlate": "1HGJ465",
        "make": "Saturn",
        "model": "SL",
        "policyLabel": "Policy Vehicle #1",
        "policySystemId": "pc:1",
        "policyVehicle": true,
        "state": {
          "code": "CA",
          "name": "California"
        },
        "vin": "1GV234TV347463345",
        "year": 1997
      },
      "vehicleDirection": {
        "code": "forward",
        "name": "Forward"
      }
    }
}

There is also a VehicleRU entity. Similar to VehicleIncident, Vehicle is also managed as an inline damageable in the VehicleRU schema. The following is a portion of a VehicleRU payload with the inline Vehicle.

{
    "data": {
        "attributes": {
            "RUNumber": 1,
            "vehicle": {
                "licensePlate": "7FDG745",
                "make": "Mercury",
                "model": "Sable",
                "state": {
                    "code": "CA",
                    "name": "California"
                },
                "vin": "6GYF54637HD645370",
                "year": 1993
            },
            "vehicleLocation": {
                "address": {
                    "addressLine1": "123 Main Street",
                    "city": "San Mateo",
                    "state": {
                        "code": "CA",
                        "name": "California"
                    }
                }
            }
        }
    }