Overview of incidents in Cloud API
In the Cloud API base configuration, every supported incident type typically has five endpoints for the CRUD operations. For example, vehicle incidents has the following endpoints:
- GET
/claims/{claimId}/vehicle-incidents
- POST
/claims/{claimId}/vehicle-incidents
- GET
/claims/{claimId}/vehicle-incidents/{incidentId}
- PATCH
/claims/{claimId}/vehicle-incidents/{incidentId}
- DELETE
/claims/{claimId}/vehicle-incidents/{incidentId}
Insurers can also add custom subtypes to the hierarchy. For more information on how to generate endpoints for custom incident subtypes, see the Cloud API Developer Guide.
Minimum creation criteria for incidents
In the base configuration, there are no required fields for creating any type of incident. All fields are optional.
Damageables
A damageable is a separate entity that stores information about the state of
an item before any loss or damage occurred. For example, the base configuration has a
Vehicle
entity, which is a damageable used by
VehicleIncident
.
- Information that is inherent to the vehicle, such as
Make
,Model
, andVin
(Vehicle identification number) is stored onVehicle
. - Information about damage to the vehicle, such as the
CollisionPoint
and whether theAirbagsDeployed
, is stored on theVehicleIncident
.
Some incident types pertain to items that must be listed on the policy. For example,
TripIncident
is an incident type that captures information about a trip
where some sort of loss occurred, such as a cancellation or lost luggage. In order to file a
claim, the trip must be listed on the travel policy. You cannot file claims for trips not
listed on the policy. These types of incidents do not typically make use of damageables.
Other incident types pertain to items that may be listed on the policy or that may belong
to a third party. For example, VehicleIncident
is an incident type that
captures information about a damaged vehicle. The vehicle could be listed on the insured's
policy. The vehicle could also be a third-party vehicle that the insured damaged. These
types of incidents typically do make use of damageables.
When an incident type has an associated damageable, you could theoretically have separate endpoints for the incident and the damageable. However, it is usually more convenient to embed the damageable information in the incident. When this is done, the damageable is referred to as an inline damageable. This is because the damageable information appears inline in the incident's schema.
PATCH behavior for incidents with damageables
- The PATCH is successful, and the resource is modified as specified in the request body.
- The PATCH fails and no changes are made.
For incidents with inline damageables on claims with verified policies, there is a third possibility.
- If the PATCH modifies fields on the inline damageable and the inline damageable is listed on the policy, ClaimCenter does not modify the existing policy damageable. Instead, ClaimCenter creates a new damageable, populates the new damageable with the information in the PATCH payload, and then associates the new damageable with the incident. The original policy damageable is still associated with the claim's policy, but it is no longer associated with the incident.
For example, suppose there is a claim with vehicle incident cc:101, which has an associated
policy vehicle cc:202. The only information on the vehicle is make
,
model
, and year
(2020 Toyota Fusion). Then, you PATCH
the vehicle, setting year
to 2010 and color
to Black.
ClaimCenter does the following:
- It creates a new vehicle. It is a non-policy vehicle with
year
set to 2010 andcolor
set to Black. (make
andmodel
are not set.) - It associated the new vehicle with vehicle incident cc:101.
- It retains vehicle cc:202, but the vehicle is no longer associated with vehicle incident cc:101. Vehciel cc:202 is associated only with the policy.
The reason for this behavior is Cloud API for ClaimCenter does not permit PATCHes to verified policy information. Information for verified policies can come only from the Policy Administration System. If you attempt to PATCH information for an inline damageable listed on the policy, ClaimCenter interprets this as a desire to create a new non-policy damageable.
This behavior can also be summarized in the following way. Whenever you PATCH an incident with an inline damageable:
- PATCHing fields that are not part of the inline damageable behaves as normal.
- PATCHing fields that are part of the inline damageable behaves as normal if the inline damageable is for a third-party object. (In other words, an object that is not listed on the policy.)
- PATCHing fields that are part of the inline damageable creates a new damageable if the inline damageable is listed on the policy.
Incompatible incident types
You cannot create an incident whose type is incompatible with the policy type. For example, you cannot create a dwelling incident on a claim associated with a personal auto policy. If you attempt to do so, Cloud API responds with an error message similar to the following:
{
"status": 404,
"errorCode": "gw.api.rest.exceptions.NotFoundException",
"userMessage": "No resource was found at path /claim/v1/claims/cc:34/dwelling-incidents"
}
Determining valid incident types for a given claim
The line of business model is a set of typelists that organizes policies, coverages, and covered losses into a single hierarchy. Collectively, these typelists define the valid types of coverages, incidents, and exposures for a given policy and type of loss.
A caller application may want to access the metadata for these typelists so that it can
determine valid incident values for a given claim. This information can be retrieved using
the Claim API's /business-line-metadata
endpoint. For more information, see
The /business-line-metadata endpoint.