Working with all policy contacts on a job

This topic describes the different ways you can work with policy contacts.

Querying for all policy contacts on a job

Use the following endpoints to retrieve information about all contacts for a specific job, regardless of their roles:

  • GET /job/v1/jobs/{jobId}/contacts
  • GET /job/v1/jobs/{jobId}/contacts/{contactId}

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

Adding a policy contact

There are two ways in which you can add a contact to a policy:

  • Create a new policy contact on the job
  • Add an existing account contact to the job

Creating a new policy contact

You can create a new policy contact directly on the job. This will add the contact to both the policy and the account.

Note: The policy must be in Draft status before you can update it with a new policy contact. To move a policy to Draft status, run the following endpoint:

POST /job/v1/jobs/{jobId}/make-draft

Required fields for creating a policy contact are the same as those for creating an account contact:

  • contactSubtype (typically set to either Person or Company)

  • firstName and lastName (for Person contacts)

  • companyName (for Company contacts)

  • primaryAddress, with at least:

    • addressLine1

    • city

    • state

    • postalCode

Note:

The preceding address information is required only if you’re not creating a contact with a linked address. See Linking policy contact addresses below for more information.

Use the following endpoint to add a new policy contact:

  • POST /job/v1/jobs/{jobId}/contacts

For example:

Command

POST /job/v1/jobs/pc:101/contacts

Request Body

{
  "data": {
    "attributes": {
        "contactSubtype": "Person",
        "firstName": "Samantha",
        "lastName": "Stewart",
        "primaryAddress": {
          "addressLine1": "2850 S. Delaware St.",
          "city": "San Mateo",
          "postalCode": "94403",
          "state": {
            "code": "CA"
          }
        }
    }
  }
}

Adding an account contact to a job

You can also add an existing account contact to a job.

To associate an existing account contact with a job's policy, use the following endpoint:

  • POST /job/v1/jobs/{jobId}/contacts

The request must include an accountContact property that specifies the ID of the existing account contact. For example, the following request adds the existing account contact pc:97 to job pc:5000.

Command

POST /job/v1/jobs/pc:5000/contacts

Request Body

{
  "data": {
    "attributes": {
        "accountContact": {
            "id": "pc:97"
        }
    }
  }
}

Modifying contact policy roles

When you create or add a policy contact, the contact is added to the underlying policy with the APDPolicyInvoledParty role. This is a generic role that simply identifies the contact as having an association with the policy.

Once the policy contact has been added, you can modify this role.

Updating and deleting policy contacts

You can update and delete policy contacts with the following endpoints:

  • PATCH /job/v1/jobs/{jobId}/contacts
  • DELETE /job/v1/jobs/{jobId}/contacts

Updating a policy contact

Use the following endpoint to PATCH a policy contact:

  • PATCH /job/v1/jobs/{jobId}/contacts

For example, the following PATCHes contact pc:44 on job pc:1001.

Command

PATCH /job/v1/jobs/pc:1001/contacts/pc:44

Request Body

{
  "data": {
    "attributes": {
        "emailAddress1": "quiltQueen71@email.com"
    }
  }
}

Note that much of the information about an account contact and a policy contact are stored in the same data model entity - the Contact entity. Therefore, when you PATCH a policy contact, changes to values stored in the Contact entity will also be reflected in the account contact.

Deleting a policy contact

When you "delete" a policy contact, the contact is not removed from PolicyCenter. Rather, the contact is removed only from the policy. The associated account contact remains on the account.

Use the following endpoint to DELETE the association between a policy contact and the policy:

  • DELETE /job/v1/jobs/{jobId}/contacts

For example, the following removed contact pc:44 from job pc:1001. (pc:44 will remain on the account.)

DELETE /job/v1/jobs/pc:1001/contacts/pc:44

<no request body>

Linking policy contact addresses

There might be times when you want a contact on a policy to have the same address as another contact on the same account. Rather than reentering the same information for every contact at the same address, you can use linked contact addresses. Linking addresses allows you to create or update a contact without reentering address information that exists elsewhere on the account, and enables you to update an address on all contacts to which it applies with a single command.

You add and update a linked address to a contact using these properties under the contact’s primaryAddress object:

  • linkedAddress: An object containing the address information to link to.

    • addressId: ID of the address to link to.

    • contactId: ID of the primary named insured, account holder, or named insured associated with that address.

  • linkedAddressUpdateMode: A value that determines how updates to the address are applied. Options are:

    • update: When this value is specified, any updates to the address will be applied to all contacts to which the address is linked.

    • unlink: Updates the address only on the contact being updated. When an address is updated with this option specified, that contact no longer has a linked address. This option removes the link, making this a stand-alone address on the contact.

After an address has been linked, it includes the following property:

  • isLinked: A Boolean value automatically set to true when an address is linked. When this value is true, updates to the address must include the linkedAddressUpdateMode property.

The following example creates a new contact with a linked address. In this example, the contact is created with the same address as the account holder. Here is the account holder information:

{
    "data": {
        "attributes": {
            "accountContactRoles": [
                {
                    "code": "NamedInsured",
                    "name": "NamedInsured"
                }
            ],
            ...
            "firstName": "Mike",
            "id": "pc:577",
            "lastName": "Sherman",
            ...
            "primaryAddress": {
                "CEDEX": "11",
                "addressLine1": "2304 Market St.",
                "addressLine2": "Floor 0000",
                "addressLine3": "Developer Unit Habitation Cube #0000",
                "addressType": {
                    "code": "business",
                    "name": "Business"
                },
                "city": "San Francisco",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA 94114",
                "id": "pc:123",
                "postalCode": "94114",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
   ...
}

Create the contact using the account holder contact id (pc:577) and address id (pc:123) in the request.

Command

POST /job/v1/jobs/pc:202/contacts

Request

{
  "data": {
    "attributes": {
        "contactSubtype": "Person",
        "firstName": "Samantha",
        "lastName": "Stewart",
        "primaryAddress": {
          "linkedAddress": {
            "addressId": "pc:123",
            "contactId":  "pc:577"
          }
        }
    }
  }
}

Response

{
    "data": {
        "attributes": {
            ...
            "firstName": "Samantha",
            "id": "pc:892",
            "lastName": "Stewart",
            ...
            "primaryAddress": {
                "CEDEX": "11",
                "addressLine1": "2304 Market St.",
                "addressLine2": "Floor 0000",
                "addressLine3": "Developer Unit Habitation Cube #0000",
                "addressType": {
                    "code": "business",
                    "name": "Business"
                },
                "city": "San Francisco",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA 94114",
                "id": "pc:125",
                "isLinked": true,
                "postalCode": "94114",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            }
        },
    ...
}

The response shows that the contact has been created with a primaryAddress that is identical to the linked address. Notice the isLinked property is set to true. If you also retrieve the contact to which you linked and view the address you linked to, you’ll see that the primaryAddress has an isLinked value of true for that contact also.

Command

GET /account/v1/accounts/pc:202/contacts/pc:577

Response

{
    "data": {
        "attributes": {
            ...
            "firstName": "Mike",
            "id": "pc:577",
            "lastName": "Sherman",
            ...
            "primaryAddress": {
                "CEDEX": "11",
                "addressLine1": "2304 Market St.",
                "addressLine2": "Floor 0000",
                "addressLine3": "Developer Unit Habitation Cube #0000",
                "addressType": {
                    "code": "business",
                    "name": "Business"
                },
                "city": "San Francisco",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA 94114",
                "id": "pc:123",
                "isLinked": true,
                "postalCode": "94114",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
    ...
}

This next example updates the address for an existing contact that has a linked address. If a contact has a linked address (isLinked is set to true), you must include a linkedAddressUpdateMode value to update the address.

Command

PATCH /job/v1/jobs/pc:202/contacts/pc:892

Request

{
  "data": {
    "attributes": {
      "primaryAddress": {
        "linkedAddressUpdateMode": "update",
        "addressLine1": "1234 Main St",
        "addressLine2": "Apt 2B",
        "addressLine3": null
      }
    }
  }
}

Response

{
    "data": {
        "attributes": {
            ...
            "firstName": "Samantha",
            "id": "pc:892",
            "lastName": "Stewart",
            ...
            "primaryAddress": {
                "CEDEX": "11",
                "addressLine1": "1234 Main St",
                "addressLine2": "Apt 2B",
                "addressType": {
                    "code": "business",
                    "name": "Business"
                },
                "city": "San Francisco",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "1234 Main St, Apt 2B, San Francisco, CA 94114",
                "id": "pc:125",
                "isLinked": true,
                "postalCode": "94114",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            }
        },
    ...
}

Because we set the linkedAddressUpdateMode to update, the linked contact’s address has also been changed:

{
    "data": {
        "attributes": {
            "firstName": "Mike",
            "id": "pc:577",
            "lastName": "Sherman",
            ...
            "primaryAddress": {
                "CEDEX": "11",
                "addressLine1": "1234 Main St",
                "addressLine2": "Apt 2B",
                "addressType": {
                    "code": "business",
                    "name": "Business"
                },
                "city": "San Francisco",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "1234 Main St, Apt 2B, San Francisco, CA 94114",
                "id": "pc:123",
                "isLinked": true,
                "postalCode": "94114",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
    ...
}

Additional behaviors

Specifying pronouns for contacts

For contacts of type Person or any of its subtypes, you can specify a set of pronouns on a contact. You can reference an existing set of pronouns from a typelist or input custom pronouns.

Use the pronounAggregate field to choose an existing set of pronouns from the PronounAggregateType typelist (for example, hehimhis). If different pronouns are desired, set this field to a value of selfidentify, and add pronouns using the following fields:
  • pronounSubjective - the person’s subjective pronoun, as a string
  • pronounObjective - the person’s objective pronoun, as a string
  • pronounPossessive - the person’s possessive pronoun, as a string

The values added to these fields are aggregated and used to populate the pronounAggregateDisplay field.

If the pronounAggregate field is changed from self-identify to one of the default values, the values in the pronounSubjective, pronounObjective, and pronounPossessive fields are cleared and set automatically. For example, if a value of sheherhers is input, pronounSubjective is set to She, pronounObjective is set to Her, and so on.

Note that these fields are available when working with contacts through Cloud API, but in the base configuration, they do not appear in the user interface.