To update contacts in your audience, use the updateContacts mutation. You can change any contact attributes except for the following:

Contact key. This is a key attribute that uniquely identifies contacts in the audience. You can assign new values to contacts without contact keys. However, existing values cannot be overwritten.
Behavior attributes such as Last interaction or Lifetime average order value. They are calculated based on user activity and cannot be edited.

Ways to identify contacts

When you run the updateContacts mutation, use contact keys to identify the contacts you want to update. Here is an example.

mutation {
  updateContacts(
    updateContactInputs: [
      {
        key: "BKQA67631"
        to: {
          attributes: [
            { name: "Email", value: "[email protected]" }
            { name: "First Name", value: "Alicia" }
          ]
        }
      }
      {
        key: "BKWA23631"
        to: {
          attributes: [
            { name: "Email", value: "[email protected]" }
            { name: "Last Name", value: "Wallace" }
          ]
        }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 2
    }
  }
}

If your audience doesn't have the Contact key attribute defined, then you must rely on addressable attributes for identification (emails and phone numbers).

mutation {
  updateContacts(
    updateContactInputs: [
      {
        addressable: [{ field: "Email", eq: "[email protected]" }]
        to: {
          attributes: [
            { name: "Phone Number", value: "+97855512000" }
            { name: "Source", value: "Google Maps" }
          ]
        }
      }
      {
        addressable: [{ field: "Phone Number", eq: "+142490300010" }]
        to: { attributes: [{ name: "Source", value: "Referral" }] }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 2
    }
  }
}

If there is a chance that there may be several entries for the same contact in your audience, you can use a combination of email address and phone number to identify a contact.

mutation {
  updateContacts(
    updateContactInputs: [
      {
        addressable: [
          { field: "Email", eq: "[email protected]" }
          { field: "Phone Number", eq: "+97855512000" }
        ]
        to: {
          attributes: [
            { name: "Phone Number", value: "+97855512999" }
            { name: "Source", value: "Offline store" }
          ]
        }
      }
    ]
  ) {
    modifiedCount
  }
}

{
  "data": {
    "updateContacts": {
      "modifiedCount": 1
    }
  }
}

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Mutation structure

Arguments

The updateContacts mutation contains the updateContactInputs argument at the top level. It's an array of objects. Each contact requires its own object.

Here are the input fields supported by objects within the updateContactInputs array.

Field	Values	Required?	Definition
`addressable`	Array of objects	Optional	You must add this field to the mutation if your audience doesn't have the key attribute. The array can contain either one object (email address or phone number) or two objects (email address and phone number). ⚠️ Do not use this field together with `key`.
`key`	String	Optional	The contact key assigned to the contact. ⚠️ Do not use this field together with `addressable`.
`to`	Array of objects	Required	Add an object for each contact attribute you want to update.

Fields nested into the addressable field (both of them are required):

Field	Values	Definition
`field`	String	The name of the addressable attribute to use for identification
`eq`	String	The value of the addressable attribute for the contact

Fields supported by objects within the to field:

Field	Nested field	Values	Definition
`attributes`	`name`	String	The name of the contact attribute you want to update
	`value`	Depends on the type of contact attribute.	The new value of the contact attribute
`consent`		Array	To update consent preferences, see Update consent statuses for contacts.

Fields

Fields returned by the updateContacts mutation:

Field	Values	Required?	Definition
`modifiedCount`	Integer	Required	The number of contacts that have been updated. 💡If some contacts haven't been found in the audience, the number will be lower than the number of contacts you submitted.

Possible error messages

Error	Definition
CONTACT_ADDRESSABLE_IS_NOT_ADDRESSABLE	Use the `key` field instead of `addressable` to submit contact keys.
CONTACT_ADDRESSABLE_SHOULD_BE_UNIQUE	An addressable value you specified is already in use. Revise the contacts before updating their attributes.
KEY_CAN_NOT_BE_REASSIGNED	A contact in your mutation already has a key. 💡Once assigned, a contact key cannot be edited.
KEY_SHOULD_BE_UNIQUE	The mutation contains a contact key that is already present in the audience. You must use a unique value.