I am able to do it when the metadata field do not receive a collection. In case of collection I receive the error

{"error":{"code":"-1, Microsoft.SharePoint.Client.ClientServiceException","message":{"lang":"en-US","value":"Cannot deserialize data for type Microsoft.SharePoint.Taxonomy.TaxonomyFieldValueCollection."}}}',
cookies: [] }

Example of what I am trying to do

 "__metadata" : {
            "type" : "SP.Data.Global_x0020_File_x0020_LibraryItem"
        "Domains_x0020__x0026__x0020_ESAs" : {
        "__metadata" : {
            "type" : "Collection(SP.Taxonomy.TaxonomyFieldValue)"
        "results" : [
                "Label" : "Family Care",
                "TermGuid" : "eb17c3ca-d402-4740-974c-0f2b31cf100b",
                "WssId" : 20
  • have a look to this post. social.msdn.microsoft.com/Forums/office/en-US/…
    – Supermode
    Feb 5 '15 at 23:40
  • when I try to do it to a field that can only receive one tag I can do it... as in the example you sent me (@Supermode) without problems... the problem is that I can receive an array of them... and I always receive that error... Feb 6 '15 at 5:30

According to eirikb's answer, I tried to implement it and I've really faced a lot of issues.

So, I'll try to be clearer and to help futur developers to handle it correctly.

Here is what worked for me:

How can I retrieve all taxonomy fields via REST API?

It exists a hidden list which will give you all the taxonomy fields:

EDIT: Sharepoint indexes this list, it means that if you add some new taxonomy fields, this list will not be up to date. In order to force the update of this list, you will have to set all your new taxonomy fields at least once on a document set metadata of taxonomy type. After that, you will be able to see them into that list. Also, it is paged after 100 items, you will have to use the call inside "__next" property of the body response in order to get the next 100 (& x) taxonomy fields.


      "IdForTerm": "19f40567-ef4c-41b0-a023-039275d66efd",
      "Term": "My test tag"
      "IdForTerm": "f2413c10-301d-4fe6-a171-ff4ad73bbafa",
      "Term": "Another tag for test"

Retrieve the hidden InternalName

Alright, but imagine you want to set one of those taxonomy fields to a metadata of a document set or a list item or whatever. How can you handle it ?

As simple as below, for our example, we will say that our metadata is named MyTaxonomySharepointField.

I actually don't know why but you will not be able to set taxonomy values by directly using the original name of your metadata (which is MyTaxonomySharepointField). For that purpose, you will have to retrieve the real InternalName which is hidden behind the metadata by suffixing it with "_0", thank you to eirikb.

Retrieve the hidden InternalName like that:


Giving you a result like:
  "d": {
          "InternalName": "p45b125f993940dca2b573bf64a02cff"

Once you'll retrieve the hidden InternalName, you will have enough infos to be able to set some taxonomy values on a metadata of TaxonomyField type.

Formatting values

A taxonomy value has to be formatted like this (according to the received properties from the TaxonomyHiddenList call):


Where if you use the first field from the TaxonomyHiddenList call, it should be rendered like:

'-1;#My test tag|19f40567-ef4c-41b0-a023-039275d66efd;'

For developers who want to set multiple values, you should use the '#' separator by concatenating your formatted values (still using my first call for the example below):

'-1;#My test tag|19f40567-ef4c-41b0-a023-039275d66efd;#-1;#Another tag for test|f2413c10-301d-4fe6-a171-ff4ad73bbafa;'

Final result

Now, here is the final datas to post for updating the metadatas of your document set (for example):

  "Title": "My new document title",
  "Description": "Here is an updated document set via REST API",
  "p45b125f993940dca2b573bf64a02cff": "-1;#My test tag|19f40567-ef4c-41b0-a023-039275d66efd;#-1;#Another tag for test|f2413c10-301d-4fe6-a171-ff4ad73bbafa;"

NB: p45b125f993940dca2b573bf64a02cff is the hidden field of your metadata MyTaxonomySharepointField

  • BTW this method to update MM with SharePoint REST also works with the MSFT Graph API, by performing a patch request with the value in the format "p45b125f993940dca2b573bf64a02cff": "-1;#My test tag|19f40567-ef4c-41b0-a023-039275d66efd" cfr docs.microsoft.com/en-us/graph/api/…
    – dc2009
    Mar 10 '20 at 10:50

Here is a working solution by Beau Cameron: http://www.aerieconsulting.com/blog/update-using-rest-to-update-a-multi-value-taxonomy-field-in-sharepoint.

I can't say it's a very nice solution, but hes done some impressive work. I have tested the hack, and it works!

To sum it up must find the InternalName of the taxonomy field which holds the value. It has same Title as your taxonomy field, just with added _0 to the title. Something like this:


When you create/update your item add that internal name as a property, with a String as value, formattedWssId;#Name|Guid;#WssId;#Name|Guid#.... E.g.,

let d = {};
d[MyMMField_0InternalName] = terms.map(term => `-1#;${term.id}|${term.name};`).join('#');

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.