Editing and deleting contacts

Editing contacts

To edit a contact, use the following endpoint:

• PATCH /contact/v1/contacts/{contactId}

To call this endpoint, the caller must have edit access to the contact. For more information on contact permissions, see the Contact Management Guide.

A PATCH changes only the fields that you include in the request. You can PATCH a contact at any time, with the following exceptions:

• A vendor contact that has active pending changes cannot be edited. Contacts that are not vendors are not subject to this restriction.
• Read-only fields and fields that can be set only when the contact is created cannot be edited. See the list of fields that you cannot edit in this section.
• You can set a field only on the contact subtypes to which it applies. For example, you cannot set firstName on a company.

You can edit all other fields of a contact, including its email addresses, phone numbers, name fields, and tax ID, provided that the field applies to the contact's subtype. The exception is that you can edit pronounObjective, pronounPossessive, and pronounSubjective only if pronounAggregate is selfidentify.

You cannot edit the following fields:

• authorizationID (string): The ID used for external authorization. The system sets this value automatically for new contacts. Always read-only.
• contactSubtype (string): The contact subtype. You can set this only when creating the contact.
• createStatus (typekey): The creation approval status of the contact. Always read-only.
• displayName (string): A system-generated label for the contact. Always read-only.
• id (string): The system-generated identifier for the contact. Always read-only.
• linkID (string): The ID that client applications use to link to the contact. You can set this only when creating the contact. Attempting to edit it returns an error.
• primaryPhone (string): The contact's primary phone number. The system derives this value from the primaryPhoneType field. Always read-only.
• pronounAggregateDisplay (string): A formatted representation of the person's aggregate pronoun. Always read-only.
• score (integer): The overall review score of the contact. Always read-only.

The following request changes the email address and work phone number of a contact:

Command

PATCH /contact/v1/contacts/ab:SNb29XOMTNzNBr6n8t4d7

Request

{
    "data": {
        "attributes": {
            "emailAddress1": "frida.kahlo@example.com",
            "workPhone": {
                "number": "415-555-0111"
            }
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "authorizationID": "SQ7bdiW0EYp2F0ZRxMnIq",
            "contactSubtype": "ABPerson",
            "createStatus": {
                "code": "approved",
                "name": "Approved"
            },
            "displayName": "Doc Test382B",
            "emailAddress1": "frida.kahlo@example.com",
            "firstName": "Doc",
            "id": "ab:SNb29XOMTNzNBr6n8t4d7",
            "lastName": "Test382B",
            "linkID": "ab:SNb29XOMTNzNBr6n8t4d7",
            "primaryAddress": {
                "displayName": "123 Melrose Lane, Yuba City, CA 95991",
                "id": "ab:S93nSRFChziOSz8vmhls5",
                "type": "ABContactAddress",
                "uri": "/contact/v1/contacts/ab:SNb29XOMTNzNBr6n8t4d7/addresses/ab:S93nSRFChziOSz8vmhls5"
            },
            "primaryPhone": "415-555-0111",
            "tagTypes": [
                {
                    "code": "client",
                    "name": "Client"
                }
            ],
            "tags": [
                {
                    "type": {
                        "code": "client",
                        "name": "Client"
                    }
                }
            ],
            "taxId": "900-00-3824",
            "workPhone": {
                "displayName": "415-555-0111",
                "number": "4155550111"
            }
        }
    }
}

Editing a contact fails with a 400 (Bad Request) error in the following cases:

• The request includes a read-only field. The error message states that the property is defined as read-only and cannot be specified on inputs.
• The request includes contactSubtype. The error message states that the property can be set only during creation and cannot be updated.
• The request includes a field that does not apply to the contact's subtype, such as firstName on a company.
• The request sets primaryAddress to null on an ABPlace. An ABPlace must always have a primary address.

Editing a contact with an unknown contactId returns a 404 (Not Found) error.

Deleting contacts

To delete a contact, use the following endpoint:

• DELETE /contact/v1/contacts/{contactId}

To call this endpoint, the caller must have delete access to the contact. For more information on contact permissions, see the Contact Management Guide.

You cannot delete a contact in the following cases:

• The contact is a vendor that has active pending changes.
• The contact is referenced by an external application (such as ClaimCenter or PolicyCenter) that is integrated with ContactManager.

The following request deletes a contact:

Command

DELETE /contact/v1/contacts/ab:SNb29XOMTNzNBr6n8t4d7

A successful DELETE returns a 204 (No Content) response with no body. Deleting a contact with an unknown contactId returns a 404 (Not Found) error.

Editing contact addresses

Addresses are always child objects to a contact. You can edit addresses, but you must do it through the parent contact.

To edit a contact address, use the following endpoint:

• PATCH /contact/v1/contacts/{contactId}/addresses/{addressId}

To call this endpoint, the caller must have edit access to the parent contact.

You can PATCH an address at any time, with the following exceptions:

• If the parent contact is a vendor with active pending changes, you cannot edit its addresses.
• If the parent contact is an ABPlace, you cannot set addressLine1, city, country, postalCode, or state to null on its primary address.
• Read-only fields cannot be edited.
• You can set a field only if it applies to the country of the address.

You can edit all other fields of an address. The fields that are available on an address depend on its country. You can change the country of an address in the same request that sets the fields that apply to the new country.

You cannot edit the following fields:

• displayName (string): The formatted value of the address. Always read-only.
• id (string): The system-generated identifier for the address. Always read-only.

The following request changes the street address, city, and postal code of an address:

Command

PATCH /contact/v1/contacts/ab:SNb29XOMTNzNBr6n8t4d7/addresses/ab:S93nSRFChziOSz8vmhls5

Request

{
    "data": {
        "attributes": {
            "addressLine1": "456 Oak Avenue",
            "city": "Marysville",
            "postalCode": "95901"
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "addressBookUID": "abc",
            "addressLine1": "456 Oak Avenue",
            "addressType": {
                "code": "business",
                "name": "Business"
            },
            "city": "Marysville",
            "country": "US",
            "description": "Mailing address",
            "displayName": "456 Oak Avenue, Marysville, CA 95901",
            "id": "ab:S93nSRFChziOSz8vmhls5",
            "postalCode": "95901",
            "spatialPoint": {
                "latitude": "39.14",
                "longitude": "-121.62"
            },
            "state": {
                "code": "CA",
                "name": "California"
            },
            "validUntil": "2030-12-31T00:00:00.000Z"
        }
    }
}

Editing an address fails with a 400 (Bad Request) error in the following cases:

• The request includes a read-only field, such as id or displayName.
• The request includes a field that does not apply to the country of the address, such as province on a United States address.
• The request sets addressLine1, city, country, postalCode, or state to null on the primary address of an ABPlace.

Editing an address with an unknown addressId, or with an addressId that does not belong to the contact, returns a 404 (Not Found) error.

Deleting contact addresses

To delete a contact address, use the following endpoint:

• DELETE /contact/v1/contacts/{contactId}/addresses/{addressId}

To call this endpoint, the caller must have edit access to the parent contact. You must delete an address through its parent contact.

You cannot delete an address in the following cases:

• The parent contact is a vendor with active pending changes.
• The address is the primary address of an ABPlace. Deleting it returns a 400 (Bad Request) error.

The following request deletes an address:

Command

DELETE /contact/v1/contacts/ab:SNb29XOMTNzNBr6n8t4d7/addresses/ab:S93nSRFChziOSz8vmhls5

The methods array in the self link of an address shows which operations are currently allowed on it. For example, the array for the primary address of an ABPlace contains get and patch but not delete.

A successful DELETE returns a 204 (No Content) response with no body. Deleting an address with an unknown addressId, or with an addressId that does not belong to the contact, returns a 404 (Not Found) error.