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, and Vin (Vehicle identification number) is stored on Vehicle.
  • Information about damage to the vehicle, such as the CollisionPoint and whether the AirbagsDeployed, is stored on the VehicleIncident.

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

For most endpoints, when you try to PATCH a resource, there is one of two outcomes:
  • 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 and color set to Black. (make and model 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.