I have been exploring the VSTS REST API lately. While there are quite a few services that require the user ID as parameter, it isn’t very obvious how you can obtain that user ID for a given user in the first place.

For my requirement I needed to get the user ID for a given user by their display name. The only way I have found to achieve this (via REST) is to use the Graph service, which is still in preview. The steps are described below.

First, we need to call the List all users service (https://[account].vssps.visualstudio.com/_apis/graph/users). This will return a list of all users. Each user record has the following structure:

{
	"subjectKind": "user",
	"domain": "Windows Live ID",
	"principalName": "[value removed]",
	"mailAddress": "[value removed]",
	"origin": "msa",
	"originId": "[value removed]",
	"displayName": "[value removed]",
	"_links": {
		"self": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/Users/msa...[value removed]" },
		"memberships": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/Memberships/msa...[value removed]" },
		"membershipState": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/MembershipStates/msa...[value removed]" },
		"storageKey": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/StorageKeys/msa...[value removed]" },
		"avatar": { "href": "https://[account].visualstudio.com/_apis/GraphProfile/MemberAvatars/msa...[value removed]" }
	},
	"url": "https://[account].vssps.visualstudio.com/_apis/Graph/Users/msa...[value removed]",
	"descriptor": "msa...[value removed]"
}

Using the displayName property we can locate the user record that we are after. We then need to invoke the service identified by the _links.storageKey property to retrieve the ID for this user. The URL of this service looks like this (value has been changed):

https://[account].vssps.visualstudio.com/_apis/Graph/StorageKeys/msa.XWI1NTUyXYZtMTzyZi09OTZhXYZmMDktXYkwZjA9NzQxZTK9

The above service returns a structure as follow:

{
	"value": "[GUID]",
	"_links": {
		"self": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/StorageKeys/msa...[value removed]" },
		"descriptor": { "href": "https://[account].vssps.visualstudio.com/_apis/Graph/Descriptors/[GUID]" 
		}
	}
}

The ID of the user can be found in the value property.

So there you have it…

Unfortunately currently it requires two calls to get the ID of a user given their display name. This might change in the future though as Microsoft’s documentation is indicating that the ability to search for user by UPN or display name is coming soon to the Graph service.