Why does the internal field names not match when working with list items using the SharePoint REST API?

Question

When I work with list items I need to use internal field names to set the field values. I have several fields of different data types, lets focus on two: 'Comment' (Multiple lines of Text) and 'Assigned' (Person or Group). I've created both myself.

This is what I use to create/update list items, and it all works fine: { "__metadata" : { "type" : "SP.Data.ListItem" }, "Comment" : "Hello", "gomsId" : 215 }

I knew to use "Comment" and "gomsId" by getting an existing list item and looking at the format I received.

The problem is: The internal field name of 'Assigned' is 'goms'. Not 'gomsId'. So when I use /_api/web/lists/getByTitle('ListName')/fields/getByTitle('Assigned')/internalname to create list items it does not work.

Why is the 'Id' part appended for this field? Is it because of the data type? How do I know which fields will have 'Id' appended and which will not?

Answer 1

For the User and Lookup field types SharePoint REST returns lookup value part only instead of User/Lookup field value (most likely for performance reasons). In that case the field name is generated according to the following format: <fieldInternalname>Id

The new field name is introduced in order to avoid a conflict with the original name since it is still possible to return it as demonstrated below:

The following query returns Id property of AssignedTo field:

/_api/web/lists/getByTitle('Workflow Tasks')/items?$select=AssignedToId

The following example returns Id and Title properties of AssignedTo field:

/_api/web/lists/getByTitle('Workflow Tasks')/items?$select=AssignedTo/Id,AssignedTo/Title&$expand=AssignedTo

---

Depending on whether field is multi-valued or not, the following formats are supported when setting User/Lookup field value via SharePoint REST API:

• single-valued user field: '<fieldname>Id' : <user id>
• multi-valued user field: '<fieldname>Id' : { 'results': [<array of user ids>] }

The following examples demonstrates how to set user field value using SharePoint 2013 REST API

Multiple user field value

The example demonstrates how to create a task item and specify multi-valued AssignedTo field:

//Create a Task item
var taskProperties = {
    '__metadata' : { 'type': 'SP.Data.TasksListItem' },
    'Title': 'Order approval',
    'AssignedToId' : { 'results': [10] }
};
createListItem(_spPageContextInfo.webAbsoluteUrl,'Tasks',taskProperties)
.done(function(data)
{
   console.log('Task has been created successfully');
})
.fail(
function(error){
    console.log(JSON.stringify(error));
});

Single user field value

The example demonstrates how to create a task item and specify a single-valued AssignedTo field:

//Create a Task item
var taskProperties = {
    '__metadata' : { 'type': 'SP.Data.TasksListItem' },
    'Title': 'Order approval',
    'AssignedToId' : 10
};
createListItem(_spPageContextInfo.webAbsoluteUrl,'Tasks',taskProperties)
.done(function(data)
{
   console.log('Task has been created successfully');
})
.fail(
function(error){
    console.log(JSON.stringify(error));
});

where

function createListItem(webUrl,listName,itemProperties) 
{    
    return $.ajax({       
       url: webUrl + "/_api/web/lists/getbytitle('" + listName + "')/items",   
       type: "POST",   
       processData: false,  
       contentType: "application/json;odata=verbose",
       data: JSON.stringify(itemProperties),
       headers: {   
          "Accept": "application/json;odata=verbose",
          "X-RequestDigest": $("#__REQUESTDIGEST").val()
       }  
    });
}