This post will show you how to update a Person/Group column value in SharePoint using the REST API, including how to clear/empty the value in the columns.
Setting a Person/Group Value
If you want to set a Person or Group column value using SharePoint’s REST API, there are a couple of things you’ll need to do. First, you’ll need to include the correct standard headers, including a X-RequestDigest value, If-Match header for consistency, Content-Type and Accept headers (easiest to use JSON for both), and X-HttpMethod. Here is a raw set of headers:
|
1 2 3 4 5 6 |
Method: POST Accept: application/json;odata=verbose Content-Type: application/json;odata=verbose X-RequestDigest: <-- your value here --> If-Match: * X-HttpMethod: POST |
…and a jQuery ajax example:
|
1 2 3 4 5 6 7 8 9 10 11 |
$.ajax({ url:'https://contoso.sharepoint.com/_api/web/lists/getbytitle('TestList')/Items', method:'POST', // --> for any type of update, best to use POST, and set X-HttpMethod below headers: { 'Accept':'application/json;odata=verbose', 'Content-Type':'application/json;odata=verbose', 'X-RequestDigest':$("#__REQUESTDIGEST").val(), 'If-Match':'*', // --> Use an etag value if you want to ensure consistency 'X-HttpMethod':'POST' // --> Only necessary for PUT,PATCH,MERGE,DELETE which some firewalls trap } }); |
Next, the name of the column in your update is not the same as the actual column name, so you’ll need to append “Id” to the end of your column. For example, if your column name is “Requestor”, you’ll need to use “RequestorId” in your request body. Below is the raw body of a POST request updating both a single-value person column, and a multi-value person column. Notice the single-value column takes an integer ID value – this is the numeric ID of the user in SharePoint from the UserInformation list in the site collection. Also notice the Multi-value columns syntax, which requires an array object to be passed to it:
|
1 2 3 4 |
{'__metadata':{'type':'SP.Data.TestListListItem'}, 'Title':'My title', 'SinglePersonColumnId':9, 'MultiPersonColumnId':{'results':[9,12]}} |
Clearing Person/Group Values
To clear out or empty the values in person or group columns, how you do it depends on if the column is single-value or multi-value.
For single-value person columns, all you have to do is set the value to -1.
|
1 2 3 4 |
" ]{'__metadata':{'type':'SP.Data.TestListListItem'}, 'Title':'My title', 'SinglePersonColumnId':-1, 'MultiPersonColumnId':{'results':[9,12]}} |
It requires an integer value, so null or empty string will give you an error: Cannot convert a primitive value to the expected type ‘Edm.Int32’.
For multi-value person columns, you have to set the results value to an empty array:
|
1 2 3 4 |
" ]{'__metadata':{'type':'SP.Data.TestListListItem'}, 'Title':'My title', 'SinglePersonColumnId':-1, 'MultiPersonColumnId':{'results':[0]}} |
That’s it!