Overview of ClaimContacts in Cloud API

The following section provides an overview of ClaimContact behavior as it exists in Cloud API.

ClaimContact roles

Every ClaimContact has a roles array. This is a read-only list of all the roles the ClaimContact has.

Every member of the roles array includes the following properties:

  • relatedTo - the type and ID of the object that the ClaimContact is related to
  • 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 not done by modifying the roles array. The way in which it is done depends on whether the role is reserved or not.

Reserved roles

A reserved role is a role that cannot be set on a ClaimContact explicitly. Instead, the role must be set implicitly 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 is reserved. A claim can have at most one reporter.)
  • Roles that are set through an array on a non-ClaimContact object. (For example, witness is reserved. A claim can have several witnesses. These witnesses are defined on the Claim resource's witnesses array.)

For more information on assigning a reserved role to a ClaimContact, see Setting reserved roles.

Non-reserved roles

A non-reserved role is a role that can be set on a ClaimContact explicitly. 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.

For more information on assigning a non-reserved role to a ClaimContact, see Setting non-reserved roles.


When specifying a ClaimContact in a payload, there are several different identifiers you can use.

  • id - The ClaimContact's system API ID. This is equal to the ClaimContact's Public ID in ClaimCenter.
  • policySystemId - An identifier in the Policy Administration System that uniquely identifies the contact.
  • refid - When the ClaimContact is being created in a given payload, other parts of the payload can reference it using an arbitrary "reference id".

For more information on the different options for identifying a ClaimContact, see Identifying the ClaimContact.

Contrasting ClaimContacts and "contacts"

The name of the resource that captures contact information is ClaimContact. This documentation refers to contacts related to claims as ClaimContacts.

Be aware that there are places where Cloud API uses the term "contacts" to refer to ClaimContacts:

  • For endpoints that have ClaimContact as the root resource, the endpoint path refers to the resources as a "contact". For example:
    • GET /claim/v1/claims/{claimId}/contacts
    • PATCH /claim/v1/claims/{claimId}/contacts/{contactId}
  • When using the include query parameter to include related ClaimContacts, the resources are referred to as "contacts". For example:
    • GET /claim/v1/claims?include=contacts

ClaimContact endpoints

You can use the following endpoints to interact with ClaimContacts directly:

Operation Endpoint Description
GET /claims/{claimId}/contacts Retrieve the ClaimContacts for a given claim
POST /claims/{claimId}/contacts Create a new ClaimContact on the given claim
GET /claims/{claimId}/contacts/{contactId} Retrieve information about the given ClaimContact
PATCH /claims/{claimId}/contacts/{contactId} Update information on the given ClaimContact
DELETE /claims/{claimId}/contacts/{contactId} Delete the given ClaimContact
GET /claims/{claimId}/contact-role-owners Retrieve a list of objects on the given claim that can have ClaimContacts associated with them

For reserved roles, you can also modify a ClaimContact indirectly by modifying the object that controls the role. For example, when you execute a PATCH /claims/{claimId} and set or modify the Claim's reporter field to a given ClaimContact, this assigns the reporter role to that ClaimContact.

The /claims/{claimId}/contact-role-owners endpoint returns all objects on the claim that can have ClaimContacts associated with them. This includes:

  • The claim itself
  • The policy
  • Any existing incidents
  • Any existing exposures
  • Any existing service requests
  • Any existing negotiations or matters
    • A negotiation is a history of the offers and counter-offers related to one disputed aspect of the loss.
    • A matter is a collection of information pertaining to a lawsuit or potential lawsuit.
Be aware that the /claims/{claimId}/contact-role-owners endpoint returns the objects that are able to have associated ClaimContacts. These objects may or may not have ClaimContacts already associated with them. If there are ClaimContacts associated with them, the ClaimContacts are not included in the response