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 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.

API Example endpoints Root resource type

GET /account/v1/accounts/{accountId}/contacts

POST /account/v1/accounts/{accountId}/contacts

GET /account/v1/accounts/{accountId}/contacts/{contactId}

PATCH /account/v1/accounts/{accountId}/contacts/{contactId}

DELETE /account/v1/accounts/{accountId}/contacts/{contactId}


GET /job/v1/accounts/{accountId}/contacts

POST /job/v1/accounts/{accountId}/contacts

GET /job/v1/accounts/{accountId}/contacts/{contactId}

PATCH /job/v1/accounts/{accountId}/contacts/{contactId}

DELETE /job/v1/accounts/{accountId}/contacts/{contactId}


GET /policy/v1/accounts/{accountId}/contacts

GET /policy/v1/accounts/{accountId}/contacts/{contactId}


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",
      "uri": "/job/v1/jobs/pc:SthuffsigqVMeo_Y1FwND/contacts/test_pp:2"

Querying for additional named insured

Use the following endpoint to retrieve a policy's additional named insured, 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 the role and a policy contact. The element specifies the account contact who has this Additional Named Insured role on the policy, and optionally the nature of the relationship between the Additional Named Insured and the primary 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/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.

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 change.