Updates a contact record.
JSON Parameters
| Name | Type | Description |
|---|---|---|
contactKey |
String | The primary address for the contact. You must provide a value for either contactKey or contactID. |
contactID |
String | The unique ID of the contact. You must provide a value for either contactKey or contactID. |
attributeSets |
Array | Required. An array that contains the data to add to the contact record. |
attributeSets.name |
String | Required. The name of the attribute group to add the contact information to. |
attributeSets.items |
Array | Required. An array of attribute entries associated with the attribute group. Each item contains the values that define the contact's information for that group. |
attributeSets.items.values |
Array | Required. Name and value pairs that indicate the attribute and its applicable value within the item. |
Usage
To update a contact record, issue a PATCH request to the /contacts/v1/contacts endpoint. The body of the request must contain either the contactKey or the contactId property. The attributeSets array contains the data to add to the contact record.
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
PATCH /contacts/v1/contacts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"contactKey":"acruz@example.com",
"contactId":12345678,
"attributeSets":[
{
"name":"Email Addresses",
"items":[
{
"values":[
{
"name":"Email Address",
"value":"acruz@example.com"
},
{
"name":"HTML Enabled",
"value":true
}
]
}
]
},
{
"name":"Email Demographics",
"items":[
{
"values":[
{
"name":"Last Name",
"value":"Cruz"
},
{
"name":"First Name",
"value":"Angela"
},
{
"name":"Text Profile Attribute",
"value":"value 1"
},
{
"name":"Number Profile Attribute",
"value":12345
}
]
}
]
},
{
"name":"MobileConnect Demographics",
"items":[
{
"values":[
{
"name":"Mobile Number",
"value":"555-555-5555"
}
]
}
]
},
{
"name":"MobilePush Demographics",
"items":[
{
"values":[
{
"name":"Device ID",
"value":958405948
},
{
"name":"Application",
"value":958405948
}
]
}
]
},
{
"name":"GroupConnect LINE Addresses",
"items":[
{
"values":[
{
"name":"Address ID",
"value":"addressId_from_api"
}
]
}
]
},
{
"name":"GroupConnect LINE Subscriptions",
"items":[
{
"values":[
{
"name":"Address ID",
"value":"addressId_from_api"
},
{
"name":"Channel ID",
"value":"1234567890"
}
]
}
]
},
{
"name":"GroupConnect LINE Demographics",
"items":[
{
"values":[
{
"name":"Address ID",
"value":"addressId_from_api"
},
{
"name":"Display Name",
"value":"display_name"
},
{
"name":"Picture Url",
"value":"picture_url"
},
{
"name":"Status Message",
"value":"status_message"
}
]
}
]
}
]
}
Example Response
After a successful request, the API returns a confirmation of the changes that were made.
{
"operationStatus": "OK",
"rowsAffected": 1,
"contactKey": "acruz@example.com",
"contactId": 12345678,
"contactTypeID": 0,
"isNewContactKey": false,
"requestServiceMessageID": "8b51b524-28c1-46fc-9a44-02fca5b0a08c",
"hasErrors": false,
"resultMessages": [],
"serviceMessageID": "80676c59-ceb9-48aa-ad35-81e150094a17"
}
If the update request fails, the API returns a 200 OK response that includes information about the failure. In this situation, the value of operationStatus is FAIL, and the resultMessages array contains details of each failure.
{
"operationStatus": "FAIL",
"rowsAffected": 0,
"requestServiceMessageID": "e7873967-3926-403b-8471-671712c3bcaf",
"responseDateTime": "2025-06-16T16:37:22.3373092-06:00",
"hasErrors": true,
"resultMessages": [
{
"formatStringParams": ["ValueDefinition", null, null, "Last Name"],
"messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "SchemaObjectNotFoundByReference",
"message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Last Name]"
},
{
"formatStringParams": ["ValueDefinition", null, null, "First Name"],
"messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "SchemaObjectNotFoundByReference",
"message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: First Name]"
},
{
"formatStringParams": ["ValueDefinition", null, null, "Country"],
"messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "SchemaObjectNotFoundByReference",
"message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Country]"
},
{
"formatStringParams": ["ValueDefinition", null, null, "Preferred Store"],
"messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "SchemaObjectNotFoundByReference",
"message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Preferred Store]"
},
{
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "InvalidAttributeSet",
"message": "The AttributeSet 'Email Addresses' must contain an 'items' array. The 'items' property cannot be null."
},
{
"resultType": "Validation",
"resultClass": "Error",
"resultCode": "InvalidAttributeSet",
"message": "The AttributeSet 'Email Addresses' contains an item with no 'values'. Each item must have at least one value."
},
{
"resultType": "Operational",
"resultClass": "Error",
"resultCode": "Update Failed",
"message": "Update failed for one or more AttributeSets. Note: Updates aren't allowed on attributes that form the primary Key of the attributeset"
}
],
"serviceMessageID": "817cdd6c-9233-4de5-b444-8e0f15ee5ee0"
}