You can update contacts in your audience using the updateContacts mutation.

Typical use cases:

• Update contact information after customers change their email addresses or phone numbers.
• Correct data entry errors discovered during data quality audits.
• Enrich contact profiles with new demographic information from customer surveys or third-party data sources.

⚠️ You cannot update the following attribute types:

• 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. Attributes like "Last interaction" or "Lifetime average order value" are calculated based on user activity and cannot be edited manually.

Ways to identify contacts

When you run the updateContacts mutation, you need to identify which contacts to update. You can use either contact keys or addressable attributes (email and phone number) depending on your audience configuration.

Identifying contacts with contact keys

If your audience uses contact keys, use the key field to identify contacts.

mutation {
  updateContacts(
    updateContactInputs: [
      {
        key: "BKQA67631"
        to: {
          attributes: [
            { name: "First Name", value: "Alicia" }
          ]
        }
      }
    ]
  ) {
    modifiedCount
  }
}

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

Example: A customer service representative receives a request to update a customer's information. Using the customer's account ID (stored as the contact key), they update the contact attributes, ensuring the correct record is modified.

Identifying contacts with addressable attributes

If your audience doesn't have the contact key attribute defined, you must rely on addressable attributes (email or phone number) for identification.

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

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

Example: A loyalty program tracks members by email address. When a member provides their phone number through a mobile app, the marketing team updates the contact record using the email as the identifier, enriching the profile with the new phone number for SMS campaigns.

Using two addressable attributes

If there is a chance that multiple contacts share the same email address or phone number in your audience, you can use a combination of both to uniquely identify a contact.

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

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

Example: A family shares an email address, resulting in multiple contacts with the same email in your audience. To update the correct person's record, you specify both their email and phone number as identifiers, ensuring only the intended contact is modified.

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 arguments

• updateContactInputs (required): Array of objects - Create a separate object for each contact you want to update.

Update contact inputs object

• addressable: Array of objects - Use this field 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). Important: Do not use this field together with key.
• key: String - The contact key assigned to the contact. Important: Do not use this field together with addressable.
• to (required): Object - Contains the attributes you want to update for the contact.

Addressable object

Used within the addressable array to identify contacts by email or phone number.

Both fields are required:

• eq (required): String - The value of the addressable attribute for the contact.
• field (required): String - The name of the addressable attribute to use for identification.

To object

Used within the updateContactInputs object to specify which attributes to update.

• attributes (required): Array of objects - Create an object for each contact attribute you want to update.
  • name (required): String - The name of the contact attribute you want to update.
  • value (required): 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.

Response fields

The mutation returns a JSON response containing:

• data (required): Object - Root response object.
  • updateContacts (required): Object - Type of operation performed.
    • modifiedCount (required): Integer - The number of contacts that have been updated. Note: 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