Additional behaviors

Masking the taxID field

The ClaimContact resource has a taxID field which stores the tax ID of the contact. In the Cloud API base configuration, this field is masked in responses so that only the last four digits appear. For example, the following is a portion of the response for a GET that retrieves a ClaimContact.

{
    "data": {
        "attributes": {
            "displayName": "Ray Newton",
            "taxId": "***-**-6789"
        }
    }
}

For some callers, such as internal or external users, the masking of tax ID may be appropriate as it protects personally identifiable information. For other callers, such as services, this masking may cause a problem as the callers may reference contacts internally using the tax ID.

There are two ways that the taxId field can be unmasked:

  • You can configure the field so that it is always unmasked. For information on how to configure this, see the Cloud API Developer Guide.
  • You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role special permissions in the Cloud API Developer Guide.

Role constraint endpoints

Role constraints

In ClaimCenter, a role constraint is an logical expression that prevent users from assigning roles to ClaimContacts in a manner that does not make business sense.

There are two types of role constraints:

  • Entity role constraint - This identifies which type of objects can make use of the role, and how many ClaimContacts can be associated with that object using that role (exactly one, at least one, at most one, or unlimited).
    • For example, this constraint could stipulate that driver (the role) can be held by ClaimContacts associated with a vehicle incident (the object), and that there can be at most one driver (how many) on a given vehicle incident.
    • This type of constraint can be thought of as both a "which type of object" constraint and a "how many" constraint.
  • Contact role type constraint - This identifies the subtype for which a given role is allowed.
    • For example, this constraint could stipulate that the role of primary doctor can be held by ClaimContacts with an associated contact whose subtype is Doctor, but not ClaimContacts with an associated contact whose subtype is Attorney.
    • This type of constraint can be thought of as a "which subtype" constraint.

In ClaimCenter, ClaimContact role constraints are configured in entityroleconstraints-config.xml. For more information, refer to the Configuration Guide.

Role constraint endpoints

You can use the following endpoints to retrieve information about role constraints.

Operation Endpoint Description
GET /role-constraints Retrieve a list of all contact role constraints for the given instance of ClaimCenter
GET /role-constraints/{contactRoleId} Retrieve information for the given contact role. Note that contactRoleId is the contact role's code, such as reporter.

These are metadata endpoints. They return information about the configuration of the given instance of ClaimCenter, not about any of its business resources.

Role constraint example: Doctor

This is a portion of the payload when GET /role-constraints/doctor is executed on the base configuration:

{
    "data": {
            "schemaConstraints": [
                {
                    "constraints": [
                        {
                            "constraintType": "ZeroToMore"
                        }
                    ],
                    "schema": "Claim"
                },
                {
                    "constraints": [
                        {
                            "constraintType": "ZeroToMore"
                        }
                    ],
                    "schema": "Exposure"
                }
            ],
            "subtype": "Doctor"
        },

From this payload, you can determine the following about doctor:

  • It can be used as a role for a ClaimContact that is associated with a claim.
    • There can be any number of doctors on an claim, including 0.
  • It can be used as a role for a ClaimContact that is associated with an exposure.
    • There can be any number of doctors on an exposure, including 0.
  • The role of doctor can only be used on ClaimContacts whose associated contact has a subtype of Doctor (or a child subtype of Doctor).

Role constraint example: Reporter

This is a portion of the payload when GET /role-constraints/reporter is executed on the base configuration:

{
    "data": {
        "attributes": {
            "schemaConstraints": [
                {
                    "constraints": [
                        {
                            "constraintType": "Exclusive"
                        },
                        {
                            "constraintType": "Required"
                        }
                    ],
                    "schema": "Claim"
                },
                {
                    "constraints": [
                        {
                            "constraintType": "ZeroToMore"
                        }
                    ],
                    "schema": "Exposure"
                }
            ]

From this payload, you can determine the following about reporter:

  • It can be used as a role for a ClaimContact that is associated with a claim.
    • The role is "exclusive". (There can be at most one ClaimContact on a Claim with this role.)
    • The role is "required". (There must be at least one ClaimContact on a Claim with this role.)
    • Taken together, these two constraints mean there must be exactly one reporter on a Claim.
  • It can be used as a role for a ClaimContact that is associated with an Exposure.
    • There can be any number of reporters on an exposure, including 0.
  • There is no subtype restriction. Therefore, the role of reporter can be used with any ClaimContact, regardless of the subtype of its associated contact.

Role owners endpoint

The /claim/v1/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 matters (A matter is a collection of information pertaining to a lawsuit or potential lawsuit.)
  • Any existing negotiations (A negotiation is a history of the offers and counter-offers related to one disputed aspect of the loss.)
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.