Policy contacts

Overview of policy contacts

In PolicyCenter, every job has an underlying policy. You can associate account contacts with this policy. For example, when a submission is created for an account, the default behavior is to associate the account's "primary insured" contact with the underlying policy as the "primary named insured". A contact associated with a policy is known as a policy contact. Policy contacts exist on policies that are unbound (such as a submission's underlying policy) and on policies that are bound.

In the PolicyCenter data model, there is no PolicyContact entity. Policy contacts are stored in the database using multiple entities:

• The Contact entity
• The AccountContact entity
• One or more PolicyContactRole entities

In Cloud API, policy contacts are managed using a single resource named PolicyContact. This resource gathers the information from multiple data model entities (Contact, AccountContact, and PolicyContactRole).

The following table summarizes the different base configuration /contact endpoints in each API and the resources used by those endpoints.

Policy contacts on a policy

For every policy:

• There is always exactly one primary insured.
• There may be one or more additional named insureds.
• There may also be contacts with roles that are specific to the policy's lines of business, such as a policy contact on a Personal Auto policy with the role of "driver".

Querying for all policy contacts

Use the following endpoints to retrieve information about all contacts for a specific policy:

• GET /policy/{policyId}/contacts
• GET /policy/{policyId}/contacts/{contactId}

These endpoints return all policy contacts, regardless of their specific role on the policy.

Querying for the primary insured

You can get a policy's named insured by retrieving the policy itself. The primaryInsured property identifies the primary named insured.

For example, the following is a portion of the response when doing a GET for policy pc:3894:

GET /policy/v1/policies/pc:3894

...
   "primaryInsured": {
      "displayName": "Ray Newton",
      "id": "test_pp:2",
      "type": "PolicyContact",
      ...
    },
...

Querying for the secondary named insured

You can get a policy's secondary insured by retrieving the policy itself. The secondaryNamedInsured property identifies the secondary named insured.

For example, the following is a portion of the response when doing a GET for policy pc:3894:

Command

GET /policy/v1/policies/pc:3894

Response

...
   "secondaryNamedInsured": {
      "displayName": "Mary Newton",
      "id": "test_pp:3",
      "type": "PolicyContact",
	...
    },
...

Querying for additional named insured

Use the following endpoints to retrieve a policy's additional named insureds, if any:

• GET policies/{policyId}/additional-named-insureds
• GET policies/{policyId}/additional-named-insureds/{additionalNamedInsuredId}

Technically speaking, each element returned by these endpoints is not a policy contact. Rather, it is information about the association between a policy contact and the additional named insured role. It can optionally specify information about this association.

For example, the following is a portion of the response when doing a GET for policy pc:3894:

GET /policy/v1/policies/pc:3894/additional-named-insureds

{
    "attributes": {
        "accountContact": {
            "displayName": "Shirley Hemsworth",
            "id": "pc:552",
            "type": "AccountContact",
            "uri": "/account/v1/accounts/pc:7071/contacts/pc:552"
        },
        "id": "353",
        "relationship": "wife"
    },

The response identifies that there is a contact with the "Additional Named Insured" role on the policy. The contact's id is pc:552 (Shirley Hemsworth), and her relationship to the primary insured is "wife". The id of the role association itself is 353.

Querying for contacts with a specified role

You can filter on policyContactRoles to retrieve all policy contacts with a given role. This example retrieves all contacts on policy pc:202 that have the role PolicySecNamedInsured:

Command

GET /policy/v1/policies/pc:202/contacts?fields=id,policyContactRoles&filter=policyContactRoles:in:PolicySecNamedInsured

Response

{
    "data": [
        {
            "attributes": {
		"id": "pc:202",
                "policyContactRoles": [
                    {
                        "code": "PolicySecNamedInsured",
                        "name": "PolicySecNamedInsured"
                    }
…
}

Masking the taxID field

The PolicyContact 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 the response for a GET that retrieves a contact.

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

For some callers, such as internal or external users, the masking of tax IDs 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.

Creating and modifying policy contacts

Policy contacts can be created or modified only from within the context of a policy transaction, such as a submission, policy change, or renewal.

To add or modify a contact on an existing policy, you must execute a policy change and execute the work from there. For more information, see Policy changes.