Account contact addresses
Account contacts are created with a primary address. An account contact can have only one primary address, but it can have multiple secondary addresses. You can add, update, and retrieve secondary addresses on an account contact. You can also replace a primary address with a secondary address, making the original primary address a secondary address. Under certain conditions, addresses might be linked with addresses on other contacts on the account.
This topic describes how to perform these actions through Cloud API.
For information on creating account contacts, see Account contacts
Retrieve addresses for an account contact
To retrieve account contact addresses for a contact, use the following endpoints:
- GET
/account/v1/accounts/{accountId}/contacts/{contactId}/addresses - GET
/account/v1/accounts/{accountId}/contacts/{contactId}/addresses/{addressId}
The following example retrieves all addresses for contact pc:340 on account pc:200.
Command
Response
In the response, notice the following property:
This property specifies whether this is a primary or secondary address. In this example the contact has only one address, so it is the primary address.
Add an address to an account contact
When an account contact is created it's required to have a primary account contact address. You can add a secondary account contact address with the following endpoint:
- POST
/account/v1/accounts/{accountId}/contacts/{contactId}/addresses
This example adds a secondary contact address to contact pc:340 on account pc:200:
Command
Request
If you do a GET to retrieve all addresses for contact pc:340, you'll now
see that there are two addresses, a primary address (primary is
true) and a secondary address (the primary property is not
present):
You can add multiple secondary addresses.
Update an account contact address
You can update an address for an account contact with the following endpoint:
- PATCH
/account/v1/accounts/{accountId}/contacts/{contactId}/addresses/{addressId}
This example updates the postal code for an account contact address:
Command
Request
You can also delete an account contact address with the following endpoint:
- DELETE
/account/v1/accounts/{accountId}/contacts/{contactId}/addresses/{addressId}
No request body is required.
Account contact addresses can be deleted only under the following circumstances:
- The address is not the primary address
- The address is not referenced or in use in a policy or policy transaction
Make an account contact address the primary address
You can make a secondary account contact address the primary address. You
can do this either when you create the address or by updating an existing secondary
address. In both cases, you set the primary property to
true in your request:
When you set a secondary address to be the primary address, the existing primary address automatically becomes a secondary address. Here are some examples.
Add an address as the primary address
Suppose there is an account contact with one address, the primary address:
Now you want to create a new address, but you want the new address to be the primary address. You can do that with this command and request:
Command
Request
By setting primary to true in the
request, the new address is now the primary, and the address that had been the
primary address is now a secondary address:
Update an address to make it the primary account contact address
You can also PATCH an address to make it the primary address. Continuing from the
preceding example, if you want to make the original address (1253 Paloma Ave)
the primary address again, update the address with primary set
to true in the request:
Command
Request
The address with ID pc:850 (1253 Paloma Ave) is now the primary address:
Linked account contact addresses
When you create an account contact, you can create it with a linked address. (For more information on linking addresses, see Linking account contact addresses.) However, you cannot create a secondary account contact address as a linked address.
Although you can't create a secondary account contact address as a linked address, it is possible for a secondary address to be a linked address. If an account contact was created with the primary contact address as a linked address, and then a new address was created and made the primary address, the address that had formerly been the primary address retains its linked address.
Here's an example:
An account contact exists with a primary address that is linked to another address on the account:
Notice the property isLinked is set to
true, indicating that this address is a linked address. Next,
add an account contact address to this contact, and make the new address the primary
address:
Command
Request
Looking at the two addresses on the account shows that the new address,
pc:935 (5678 Bailey Street), is the primary address for this account contact. The
address that used to be the primary address (ID pc:802, address 1234 Vista Drive) is
now a secondary address and is still linked (isLinked is still
true).
You can also create a new account contact with an address that is linked to another contact's secondary address. At that point, the primary contact address of the new contact and the secondary address of the first contact are both linked addresses.
To update an account contact address that is linked you must include the
linkedAddressUpdateMode property. This property must have one
of the following values assigned:
update: Setting this value updates the address for the given contact and for all other contacts with addresses linked to the address being updated.unlink: Setting this value updates the address only for the contact being updated; addresses linked to that address are not updated. This option removes the link for the address on this contact, making it a stand-alone address on the contact.
This example updates a linked address and all addresses to which it is linked.
Command
Request