Working with all policy contacts on a job
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 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.
Adding an account contact to a job
You can add an account contact to a job. When you do this, the contact is added to the
underlying policy with the APDPolicyInvoledParty
role. This is a
generic role that simply identifies the contact has an association with the policy.
To associate an 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 with the APDPolicyInvoledParty
role.
POST /job/v1/jobs/{jobId}/contacts/pc:5000
{
"data": {
"attributes": {
"accountContact": {
"id": "pc:97"
}
}
}
}
Note that, from the perspective of the job, you cannot create new contacts. You can only associate existing account contacts to the job's policy. If the desired contact does not exist, you must first create it as an account contact and then associate it with the job's policy. For information on creating account contacts, see Creating account contacts.
Once the account contact is associated with the policy, you can modify the contact's policy roles.
- To make the contact the primary named insured on the policy, see Primary named insured contacts.
- To make the contact an additional named insured on the policy, see Adding additional named insureds.
PATCHing and DELETEing policy contacts
PATCHing 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.
PATCH /job/v1/jobs/pc:1001/contacts/pc:44
{
"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.
DELETEing 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>