Getting Formatted values using Web API

In our earlier post we discussed how we can fetch data using retrieve and retrievemultiple request. We demonstrated how we can include different fields from primary entity. In this post we are going to discuss how we can fetch additional information (formatted values) and related entity properties.

In our retrieve example we included single valued navigation property using _navigationpropertyname_value which returns only GUID of the single valued property (lookup field), but if we want to get text value of the lookup field we can change request header to include formatted values. Also if you have experience in writing OData query, you might be aware of that to get option set text (a very common request) we need to write additional metadata request using SOAP. But using Web API, we can simply include following header request, and it will return both option set value and text, if we have any option set field in our query.

req.setRequestHeader("Prefer", "odata.include-annotations=OData.Community.Display.V1.FormattedValue");

So we can modify our earlier request and it will look like below:

function retrieveEntity(entityName, Id, columnSet) {
    var serverURL = Xrm.Page.context.getClientUrl();
    var Query = entityName + "(" + Id + ")" + columnSet;
    var req = new XMLHttpRequest();"GET", serverURL + "/api/data/v8.0/" + Query, true);
    req.setRequestHeader("Accept", "application/json");
    req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
    req.setRequestHeader("OData-MaxVersion", "4.0");
    req.setRequestHeader("OData-Version", "4.0");
    req.setRequestHeader("Prefer", "odata.include-annotations=OData.Community.Display.V1.FormattedValue");
    req.onreadystatechange = function() {
        if (this.readyState == 4 /* complete */ ) {
            req.onreadystatechange = null;
            if (this.status == 200) {
                var data = JSON.parse(this.response);
                if (data != null {
                        alert(data["_primarycontactid_value@OData.Community.Display.V1.FormattedValue"]); //for lookup text
                        alert(data["paymenttermscode@OData.Community.Display.V1.FormattedValue"]); //for optionset text
                } else {
                    var error = JSON.parse(this.response).error;

We can see in watch window it will return details like below:
Now let’s say we want to get additional properties from related entities, for example while query account record, we want to include some of the properties from the primary contact record as well, so to include related entity properties, we can utilize $expend clause just like we can do in OData using following option:

var columnSet="?$select=accountnumber&$expand=primarycontactid";

In above query, we have included $expend with the name of the single valued navigation property, so as result, we will get all properties of the primary contact like below in our response:

We can also select which properties we want to get from navigation like below, instead of all (by default it will return all properties):


Similarly we can fetch data from collection valued navigation properties using relationship name like below:


In above query him_building_account is the name of N:N relationship that we created in our last post.Apart from returning limited properties we can also apply other clauses like $filter, $orderby and $top in our query for navigation properties.

Stay tuned for more Web API Samples !!

Leave a Reply