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 torole
- the role the ClaimContact has on that objectactive
- 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'switnesses
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.
Identifiers
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}
- GET
- 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
- GET
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.
/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