Account contacts
In addition to the account holder, an account may have any number of additional contacts.
Querying for account contacts
Use the following endpoints to retrieve information about contacts for a specific account:
- GET
/accounts/{accountId}/contacts
- GET
/accounts/{accountId}/contacts/{contactId}
Masking the taxID
field
The AccountContact
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.
Creating account contacts
Use the following endpoint to create an AccountContact
for a given
account:
- POST
/accounts/{accountId}/contacts
Minimum creation criteria
You must specify the following information:
contactSubtype
(typically set to eitherPerson
orCompany
)firstName
andlastName
(forPerson
contacts)companyName
(forCompany
contacts)primaryAddress
, with at least:addressLine1
city
state
postalCode
The preceding address information is not required if you’re creating a contact with a linked address. See Linking account contact addresses below for more information.
For example, the following request creates a new contact for account pc:202.
Command
POST /account/v1/accounts/pc:202/contacts
Request
{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
}
}
Modifying account contacts
Use the following endpoints to modify or delete an account contact:
- PATCH
/account/v1/accounts/{accountId}/contacts/{contactId}
- DELETE
/account/v1/accounts/{accountId}/contacts/{contactId}
For example, the following request assigns an email for account contact pc:444 on account pc:202.
Command
PATCH /account/v1/accounts/pc:202/contacts/pc:444
Request
{
"data": {
"attributes": {
"emailAddress1": "sstewart@email.com"
}
}
}
The following request deletes account contact pc:444 on account pc:202.
DELETE /account/v1/accounts/pc:202/contacts/pc:444
<no request body>
Linking account contact addresses
There might be times when you want a contact on an account to have the same address as another contact on that 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 totrue
when an address is linked. When this value is true, updates to the address must include thelinkedAddressUpdateMode
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": "AccountHolder",
"name": "AccountHolder"
}
],
...
"firstName": "Alicia",
"id": "pc:577",
"lastName": "Shirley",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo, CA 94404-0399",
"id": "pc:123",
"postalCode": "94404-0399",
"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 /account/v1/accounts/pc:202/contacts
Request
{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"linkedAddress": {
"addressId": "pc:123",
"contactId": "pc:577"
}
}
}
}
}
Response
{
"data": {
"attributes": {
...
"id": "pc:892",
"lastName": "Stewart",
"officialIds": {},
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo, CA 94404-0399",
"id": "pc:3333",
"isLinked": true,
"postalCode": "94404-0399",
"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": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo, CA 94404-0399",
"id": "pc:123",
"isLinked": true,
"postalCode": "94404-0399",
"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 /account/v1/accounts/pc:202/contacts/pc:892
Request
{
"data": {
"attributes": {
"primaryAddress": {
"linkedAddressUpdateMode": "update",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressLine3": null
}
}
}
}
Response
{
"data": {
"attributes": {
...
"id": "pc:892",
"lastName": "Stewart",
"officialIds": {},
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "1234 Main St, Apt 2B, San Mateo, CA 94404-0399",
"id": "pc:5555",
"isLinked": true,
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
}
},
Because we set the linkedAddressUpdateMode
to update
,
the linked contact’s address has also been changed:
{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
...
"firstName": "Alicia",
"id": "pc:577",
"lastName": "Shirley",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "1234 Main St, Apt 2B, San Mateo, CA 94404-0399",
"id": "pc:123",
"isLinked": true,
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
},
...
},