ClaimContact roles

ClaimContact roles and role owners

Every ClaimContact must have at least one contact role. A contact role is a name that identifies the type of relationship the ClaimContact has on the claim. For example, on claim 523-45-111341:

  • Ray Newton could be the reporter on the claim itself.
  • Ray Newton could be the insured on the policy.
  • Debbie Newton could an alternate contact on the claim itself.
  • Stan Davidson could the driver of vehicle cc:4322.
  • Mike's Auto Body Repair could be the auto repair shop for vehicle cc:4322.

Notice that every contact role applies to a specific object, which is either the claim or a child object of the claim (the policy, a vehicle, an exposure, and so on.) In ClaimCenter, this is referred to as the role owner. In Cloud API, the field that references this object is the relatedTo field.

Reserved and non-reserved roles

In Cloud API, every contact role type (such as reporter or witness) can be classified as either reserved or non-reserved.

Reserved roles

A reserved role is a role that cannot be set directly on a ClaimContact. Instead, the role must be set indirectly through a field, array, or action on another object.

For example, reporter is a reserved role. You cannot add this role directly to a ClaimContact. However, you can set a Claim's reporter field to a given ClaimContact. This implicitly adds the reporter role to that ClaimContact. This also removes the reporter role from any other ClaimContact that previous had it.

The reserved roles are defined in the ReservedContactRoles.yaml file in the integration/contactroles/v1 directory. In general, the reserved roles are either:

  • Roles for which there can be at most one ClaimContact with the role. (For example, reporter. A claim can have at most one reporter.)
  • Roles that are set through an array on a non-ClaimContact object. (For example, witness. Witnesses are defined on the Claim resource's witnesses array.)

Non-reserved roles

A non-reserved role is a role that can be set on a ClaimContact directly. Every role that is not listed in the ReservedContactRoles.yaml file is a non-reserved role. For example, alternate contact is a non-reserved role. A claim can have any number of alternate contacts, and this type of ClaimContact is not managed by an array on Claim.

Roles array properties

The ClaimContact resource has two role-related array properties:

  • roles - A read-only array of all roles held by the ClaimContact
  • editableRoles - An editable array of non-reserved roles held by the ClaimContact

Both properties use the ContactRole schema.

Every member of these arrays includes the following properties:

  • relatedTo - the type and ID of the object that the ClaimContact is related to (the "role owner")
  • role - the role the ClaimContact has on that object
  • active - a Boolean identifying whether the ClaimContact actively holds the role on the claim.

The active field is used to identify ClaimContacts who previously held a role on the claim but are no longer actively involved in the claim. For example, suppose an injured person is treated by one doctor, but then the case is reassigned to a second doctor. Both doctors could be ClaimContacts on the claim, but active would be set to true only for the second doctor.

You can modify the roles a ClaimContact has, but this is never done by modifying the roles array. Instead, you either modify a field or array on a related object, or you modify the editableRoles array. Which approach to use is determined by whether the role is reserved or not.