Policy contact addresses

Policy contacts are created with a primary address. A policy contact can have only one primary address, but it can have multiple secondary addresses. You can add, update, and retrieve secondary addresses on a policy 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 more information on policy contacts, see Working with all policy contacts on a job

Retrieve contact addresses

You can retrieve policy contact addresses using the following endpoints:

  • GET /job/v1/jobs/{jobId}/contacts/{contactId}/addresses
  • GET /job/v1/jobs/{jobId}/contacts/{contactId}/addresses/{addressId}
  • GET /policy/v1/policies/{policyId}/contacts/{contactId}/addresses
  • GET /policy/v1/policies/{policyId}/contacts/{contactId}/addresses/{addressId}

The following example retrieves all addresses for contact pc:340 on job pc:200.

Command

GET /job/v1/jobs/pc:200/contacts/pc:340/addresses

Response

{
  "count": 1,
  "data": [
    {
      "attributes": {
        "CEDEX": "11",
        "addressLine1": "1253 Paloma Ave",
        "addressLine2": "Floor 0000",
        "addressLine3": "Developer Unit Habitation Cube #0000",
        "addressType": {
          "code": "home",
          "name": "Home"
        },
        "city": "Arcadia",
        "country": "US",
        "county": "San Mateo",
        "description": "Created by the Address Builder with code 0",
        "displayName": "1253 Paloma Ave, Floor 0000, Developer Unit Habitation Cube #0000, Arcadia, CA 91007",
        "id": "pc:850",
        "postalCode": "91007",
        "primary": true,
        "state": {
          "code": "CA",
          "name": "California"
        }
      },
    ],

In the response, notice the following property:

"primary": true

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 a contact address to a job

When a policy contact is created it's required to have a primary contact address. (For information on creating policy contacts, see Working with all policy contacts on a job.) You can add a secondary contact address with the following endpoint:

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

Adding a new secondary address to a contact on a policy also adds that address to the contact on the account. For information on working with contact addresses on an account, see Account contact addresses.

This example adds a secondary contact address to contact pc:340 on job pc:200:

Command

POST /job/v1/jobs/pc:200/contacts/pc:340/addresses

Request

{
  "data": {
    "attributes": {
      "addressLine1": "1234 Vista Drive",
      "city": "Glendale",
      "postalCode": "91020",
      "state": {
        "code": "CA"
      }
    }
  }
}

If you do a GET to retrieve all addresses for contact pc:340 on job pc:200, 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):

{
  "count": 2,
  "data": [
    {
      "attributes": {
        "addressLine1": "1234 Vista Drive",
        "city": "Glendale",
        "country": "US",
        "displayName": "1234 Vista Drive, Glendale, CA 91020",
        "id": "pc:875",
        "postalCode": "91020",
        "state": {
          "code": "CA",
          "name": "California"
        }
      …
    },
    {
      "attributes": {
        "CEDEX": "11",
        "addressLine1": "1253 Paloma Ave",
        "addressLine2": "Floor 0000",
        "addressLine3": "Developer Unit Habitation Cube #0000",
        "addressType": {
          "code": "home",
          "name": "Home"
        },
        "city": "Arcadia",
        "country": "US",
        "county": "San Mateo",
        "description": "Created by the Address Builder with code 0",
        "displayName": "1253 Paloma Ave, Floor 0000, Developer Unit Habitation Cube #0000, Arcadia, CA 91007",
        "id": "pc:850",
        "postalCode": "91007",
        "primary": true,
        "state": {
          "code": "CA",
          "name": "California"
        }
      },
     …
}

You can add multiple secondary addresses.

Update a contact address on a job

You can update an address for a policy contact with the following endpoint:

  • PATCH /job/v1/jobs/{jobId}/contacts/{contactId}/addresses/{addressId}

Updating a contact's address on the policy does not update that address on the account.

This example updates the postal code for a policy contact address:

Command

PATCH /job/v1/jobs/pc:200/contacts/pc:340/addresses/pc:875

Request

{
    "data": {
        "attributes": {
            "postalCode": "91203"
        }
    }
}

You can also delete a policy contact address with the following endpoint:

  • DELETE /job/v1/jobs/{accountId}/contacts/{contactId}/addresses/{addressId}

No request body is required.

A policy contact address 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

Deleting the address removes that address from that contact on the job and the account.

Make a contact address the primary address on a job

You can make a secondary policy 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:

"primary": true

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 a contact address as the primary address

Suppose there is a job with a policy contact that has one address, the primary address:

{
  "count": 1,
  "data": [
    {
      "attributes": {
        "CEDEX": "11",
        "addressLine1": "1253 Paloma Ave",
        "addressLine2": "Floor 0000",
        "addressLine3": "Developer Unit Habitation Cube #0000",
        "addressType": {
          "code": "home",
          "name": "Home"
        },
        "city": "Arcadia",
        "country": "US",
        "county": "San Mateo",
        "description": "Created by the Address Builder with code 0",
        "displayName": "1253 Paloma Ave, Floor 0000, Developer Unit Habitation Cube #0000, Arcadia, CA 91007",
        "id": "pc:850",
        "postalCode": "91007",
        "primary": true,
        "state": {
          "code": "CA",
          "name": "California"
        }
      },
    ],

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

POST /job/v1/jobs/pc:200/contacts/pc:340/addresses

Request

{
    "data": {
        "attributes": {
            "addressLine1": "1234 Vista Drive",
            "city": "Glendale",
            "postalCode": "91020",
            "state": {
                "code": "CA"
            },
            "primary": true
        }
    }
}

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:

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "addressLine1": "1234 Vista Drive",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Glendale",
                "country": "US",
                "displayName": "1234 Vista Drive, Glendale, CA 91020",
                "id": "pc:875",
                "postalCode": "91020",
                "primary": true,
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
           …
        {
            "attributes": {
                "CEDEX": "11",
                "addressLine1": "1253 Paloma Ave",
                "addressLine2": "Floor 0000",
                "addressLine3": "Developer Unit Habitation Cube #0000",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Arcadia",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "1253 Paloma Ave, Floor 0000, Developer Unit Habitation Cube #0000, Arcadia, CA 91007",
                "id": "pc:850",
                "postalCode": "91007",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
          …
    ],

Update an address to make it the primary policy contact address

You can also PATCH an address to make it the primary address. Continuing from the example in the previous section, 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

PATCH /job/v1/jobs/pc:200/contacts/pc:340/addresses/pc:850

Request

{
    "data": {
        "attributes": {
            "primary": true
        }
    }
}

The address with ID pc:850 (1253 Paloma Ave) is now the primary address:

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "addressLine1": "1234 Vista Drive",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Glendale",
                "country": "US",
                "displayName": "1234 Vista Drive, Glendale, CA 91020",
                "id": "pc:875",
                "postalCode": "91020",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
...
        },
        {
            "attributes": {
                "CEDEX": "11",
                "addressLine1": "1253 Paloma Ave",
                "addressLine2": "Floor 0000",
                "addressLine3": "Developer Unit Habitation Cube #0000",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Arcadia",
                "country": "US",
                "county": "San Mateo",
                "description": "Created by the Address Builder with code 0",
                "displayName": "1253 Paloma Ave, Floor 0000, Developer Unit Habitation Cube #0000, Arcadia, CA 91007",
                "id": "pc:850",
                "postalCode": "91007",
                "primary": true,
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
...
}

Linked policy contact addresses

When you create a policy contact on a job, you can create it with a linked address. (For information on linking addresses, see Linking policy contact addresses.) However, you cannot create a secondary policy contact address as a linked address.

Although you can't create a secondary policy contact address as a linked address, it is possible for a secondary address to be a linked address. If a policy 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:

A policy contact exists with a primary address that is linked to another address on the account:

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "addressLine1": "1234 Vista Drive",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Glendale",
                "country": "US",
                "displayName": "1234 Vista Drive, Glendale, CA 91020",
                "id": "pc:802",
                "isLinked": true,
                "postalCode": "91020",
                "primary": true,
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
          …
        },

Notice the property isLinked is set to true, indicating that this address is a linked address. Next, add a policy contact address to this contact, and make the new address the primary address:

Command

POST /job/v1/jobs/pc:200/contacts/pc:340/addresses

Request

{
    "data": {
        "attributes": {
            "addressLine1": "5678 Bailey Street",
            "city": "Glendale",
            "postalCode": "91020",
            "state": {
                "code": "CA"
            },
            "primary": true
        }
    }
}

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).

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "addressLine1": "1234 Vista Drive",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Glendale",
                "country": "US",
                "displayName": "1234 Vista Drive, Glendale, CA 91020",
                "id": "pc:802",
                "isLinked": true,
                "postalCode": "91020",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
          …
        },
        {
            "attributes": {
                "addressLine1": "5678 Bailey Street",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "Glendale",
                "country": "US",
                "displayName": "5678 Bailey Street, Glendale, CA 91020",
                "id": "pc:935",
                "postalCode": "91020",
                "primary": true,
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },

You can also create a new policy 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 a policy 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

PATCH /job/v1/jobs/pc:200/contacts/pc:340/addresses/pc:802

Request

{
    "data": {
        "attributes": {
            "linkedAddressUpdateMode: "update",
            "postalCode": "91203"
        }
    }
}