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. It is set when a contact is created and doesn't change after that.
- 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 Contact key attribute. The array can contain either one object (email address or phone number) or two objects (email address and phone number). |
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:
Field | Values | Required? | Definition |
---|---|---|---|
field | String | Required | The name of the addressable attribute to use for identification |
eq | String | Required | The value of the addressable attribute for the contact |
Fields nested into the to
field:
Field | Nested field | Required? | Values | Definition |
---|---|---|---|---|
attributes | 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. |
Fields
Fields returned by the updateContacts
mutation:
Field | Values | Required? | Definition |
---|---|---|---|
modifiedCount | Integer | Required | The number of contacts that have been updated |
Possible error messages
Error | Definition |
---|---|
CONTACT_ADDRESSABLE_IS_NOT_ADDRESSABLE | Use the key field instead of addressable to submit contact keys. |
CONTACT_ADDRESSABLE_NOT_ALLOWED_WHEN_CONTACT_KEY_DEFINED | Your audience has the Contact key attribute defined. You must use contact keys for identification. If you have a contact without a contact key, the only way to edit it is through the Connect application. |
CONTACT_ADDRESSABLE_SHOULD_BE_UNIQUE | The addressable value you specified is shared by several contacts in the audience. Revise the contacts before updating their attributes. |
CONTACT_NOT_FOUND_BY_KEY | A contact with the specified identifier is not available in the audience. Use the Get all contacts query to get the list of existing contacts. |