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 incidents that do not have a damageable: Additional work for the incident endpoints
- For incidents that do have a damageable: Additional work for the incident endpoints
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}
- GET
- 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}
- GET
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"
}
}
}
}
}