PATCH /contacts/v1/contacts

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.values`	Array	An array of name and value pairs that indicate the attribute and applicable value.

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.

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2PATCH /contacts/v1/contacts
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7  "contactKey":"acruz@example.com",
8  "contactId":12345678,
9  "attributeSets":[
10    {
11      "name":"Email Addresses",
12      "items":[
13        {
14          "values":[
15            {
16              "name":"Email Address",
17              "value":"acruz@example.com"
18            },
19            {
20              "name":"HTML Enabled",
21              "value":true
22            }
23          ]
24        }
25      ]
26    },
27    {
28      "name":"Email Demographics",
29      "items":[
30        {
31          "values":[
32            {
33              "name":"Last Name",
34              "value":"Cruz"
35            },
36            {
37              "name":"First Name",
38              "value":"Angela"
39            },
40            {
41              "name":"Text Profile Attribute",
42              "value":"value 1"
43            },
44            {
45              "name":"Number Profile Attribute",
46              "value":12345
47            }
48          ]
49        }
50      ]
51    },
52    {
53      "name":"MobileConnect Demographics",
54      "items":[
55        {
56          "values":[
57            {
58              "name":"Mobile Number",
59              "value":"555-555-5555"
60            }
61          ]
62        }
63      ]
64    },
65    {
66      "name":"MobilePush Demographics",
67      "items":[
68        {
69          "values":[
70            {
71              "name":"Device ID",
72              "value":958405948
73            },
74            {
75              "name":"Application",
76              "value":958405948
77            }
78          ]
79        }
80      ]
81    },
82    {
83      "name":"GroupConnect LINE Addresses",
84      "items":[
85        {
86          "values":[
87            {
88              "name":"Address ID",
89              "value":"addressId_from_api"
90            }
91          ]
92        }
93      ]
94    },
95    {
96      "name":"GroupConnect LINE Subscriptions",
97      "items":[
98        {
99          "values":[
100            {
101              "name":"Address ID",
102              "value":"addressId_from_api"
103            },
104            {
105              "name":"Channel ID",
106              "value":"1234567890"
107            }
108          ]
109        }
110      ]
111    },
112    {
113      "name":"GroupConnect LINE Demographics",
114      "items":[
115        {
116          "values":[
117            {
118              "name":"Address ID",
119              "value":"addressId_from_api"
120            },
121            {
122              "name":"Display Name",
123              "value":"display_name"
124            },
125            {
126              "name":"Picture Url",
127              "value":"picture_url"
128            },
129            {
130              "name":"Status Message",
131              "value":"status_message"
132            }
133          ]
134        }
135      ]
136    }
137  ]
138}

After a successful request, the API returns a confirmation of the changes that were made.

1{
2  "operationStatus": "OK",
3  "rowsAffected": 1,
4  "contactKey": "acruz@example.com",
5  "contactId": 12345678,
6  "contactTypeID": 0,
7  "isNewContactKey": false,
8  "requestServiceMessageID": "8b51b524-28c1-46fc-9a44-02fca5b0a08c",
9  "hasErrors": false,
10  "resultMessages": [],
11  "serviceMessageID": "80676c59-ceb9-48aa-ad35-81e150094a17"
12}

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.

1{
2  "operationStatus": "FAIL",
3  "rowsAffected": 0,
4  "requestServiceMessageID": "e7873967-3926-403b-8471-671712c3bcaf",
5  "responseDateTime": "2025-06-16T16:37:22.3373092-06:00",
6  "hasErrors": true,
7  "resultMessages": [
8    {
9      "formatStringParams": ["ValueDefinition", null, null, "Last Name"],
10      "messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
11      "resultType": "Validation",
12      "resultClass": "Error",
13      "resultCode": "SchemaObjectNotFoundByReference",
14      "message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Last Name]"
15    },
16    {
17      "formatStringParams": ["ValueDefinition", null, null, "First Name"],
18      "messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
19      "resultType": "Validation",
20      "resultClass": "Error",
21      "resultCode": "SchemaObjectNotFoundByReference",
22      "message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: First Name]"
23    },
24    {
25      "formatStringParams": ["ValueDefinition", null, null, "Country"],
26      "messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
27      "resultType": "Validation",
28      "resultClass": "Error",
29      "resultCode": "SchemaObjectNotFoundByReference",
30      "message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Country]"
31    },
32    {
33      "formatStringParams": ["ValueDefinition", null, null, "Preferred Store"],
34      "messageFormatString": "Unable to resolve schema element of type: {0} by reference. [Id: {1}, Key: {2}, Name: {3}]",
35      "resultType": "Validation",
36      "resultClass": "Error",
37      "resultCode": "SchemaObjectNotFoundByReference",
38      "message": "Unable to resolve schema element of type: ValueDefinition by reference. [Id: , Key: , Name: Preferred Store]"
39    },
40    {
41      "resultType": "Operational",
42      "resultClass": "Error",
43      "resultCode": "Update Failed",
44      "message": "Update failed for one or more AttributeSets. Note: Updates aren't allowed on attributes that form the primary Key of the attributeset"
45    }
46  ],
47  "serviceMessageID": "817cdd6c-9233-4de5-b444-8e0f15ee5ee0"
48}

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!