Postal addresses

Postal addresses can be created either when the contact is created (using request inclusion) or after the contact has been created. Both make use of the POST /contacts/{contactId}/addresses endpoint.

A new postal address can either be the primary address or a secondary address.

Primary addresses

A contact is not required to have a primary address. If it does, it can have up to one primary address.

Note that, in order for a contact to be included in a proximity search, it must have a primary address, and the primary address must be geocoded with a spatial point specifying longitude and latitude. The spatial point can be set through the ContactManager geocoding batch process, or through a Cloud API POST or PATCH. For more information on the ContactManager geocoding batch process, see the Contact Management Guide.

Creating a new contact with a primary address

The following creates a minimal ABPerson and a primary address using request inclusion:

POST contact/v1/contacts

{
  "data": {
    "attributes": {
            "contactSubtype": "ABPerson",
            "lastName": "Pisano",
            "tags": [
                {
                    "type": {
                        "code": "client"
                    }
                }
            ],
            "taxId": "000-00-0003",
            "primaryAddress": {
              "refid": "newAddress"
            }
      }
  },  
    "included": {
      "ABContactAddress": [
        {
          "attributes": {
            "addressLine1": "123 Melrose Lane",
            "city": "Yuba City",
            "state": {
                "code" : "CA"
            }
          },
          "refid": "newAddress",
          "method": "post",
          "uri": "/contact/v1/contacts/this/addresses"
        }
      ]
    }
}

Creating a new primary address for an existing contact

If the contact already exists, you can PATCH the contact to create a new address and make it the primary address. If the contact already has a primary address, the primary address will be automatically reset to the new address.

The following is an example of adding a new primary address for an existing contact with id ab:201:

PATCH contact/v1/contacts/ab:201

{
  "data": {
    "attributes": {
            "primaryAddress": {
              "refid": "newAddress"
            }
      }
  },  
    "included": {
      "ABContactAddress": [
        {
          "attributes": {
            "addressLine1": "123 Melrose Lane",
            "city": "Yuba City",
            "state": {
                "code" : "CA"
            }
          },
          "refid": "newAddress",
          "method": "post",
          "uri": "/contact/v1/contacts/ab:201/addresses"
        }
      ]
    }
}

Secondary addresses

A contact can have any number of secondary addresses.

Creating a new contact with a secondary address

The following creates a minimal ABPerson and a secondary address using request inclusion:

POST contact/v1/contacts

{
  "data": {
    "attributes": {
            "contactSubtype": "ABPerson",
            "lastName": "Pisano",
            "tags": [
                {
                    "type": {
                        "code": "client"
                    }
                }
            ],
            "taxId": "000-00-0003"
      }
  },  
    "included": {
      "ABContactAddress": [
        {
          "attributes": {
            "addressLine1": "123 Melrose Lane",
            "city": "Yuba City",
            "state": {
                "code": "CA"
            }
          },
          "method": "post",
          "uri": "/contact/v1/contacts/this/addresses"
        }
      ]
    }
}

Creating a new secondary address for an existing contact

The following creates a secondary address for an existing ABPerson with id ab:153.

POST contact/v1/contacts/ab:153/addresses

{
  "data": {
    "attributes": {
            "addressLine1": "1515 Emmerson Street",
            "city": "Golden",
            "state": {
                "code": "CO"
            }
      }
  }
}