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 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 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 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": "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"
                }
            },
            ...
        },