Create personName

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Use this API to create a new personName object in a user's profile.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All
Delegated (personal Microsoft account)	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All
Application	User.ReadBasic.All, User.Read.All, User.ReadWrite.All

HTTP request

POST /me/profile/names
POST /users/{id | userPrincipalName}/profile/names

Request headers

Name	Description
Authorization	Bearer {token}. Required.
Content-Type	application/json. Required.

Request body

In the request body, supply a JSON representation of the personName object.

The following table shows the properties that are possible to set when you create a personName object.

Property	Type	Description
allowedAudiences	String	The audiences that are able to see the values contained within the entity. Inherited from itemFacet. Possible values are: me, family, contacts, groupMembers, organization, federatedOrganizations, everyone, unknownFutureValue.
displayName	String	Provides an ordered rendering of firstName and lastName depending on the locale of the user or their device.
first	String	First name of the user.
id	String	Identifier used for individually addressing the entity. Inherited from entity
inference	inferenceData	Contains inference detail if the entity is inferred by the creating or modifying application. Inherited from itemFacet.
initials	String	Initials of the user.
languageTag	String	Contains the name for the language (en-US, no-NB, en-AU) following IETF BCP47 format.
last	String	Last name of the user.
maiden	String	Maiden name of the user.
middle	String	Middle name of the user.
nickname	String	Nickname of the user.
pronunciation	yomiPersonName	Guidance on how to pronounce the users name.
suffix	String	Designators used after the users name (eg: PhD.)
title	String	Honorifics used to prefix a users name (eg: Dr, Sir, Madam, Mrs.)

Response

If successful, this method returns 201, Created response code and a new personName object in the response body.

Examples

Request

The following is an example of the request.

HTTP

POST https://graph.microsoft.com/beta/me/profile/names
Content-type: application/json

{
  "displayName": "Innocenty Popov",
  "first": "Innocenty",
  "initials": "IP",
  "last": "Popov",
  "languageTag": "en-US",
  "maiden": null
}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var personName = new PersonName
{
	DisplayName = "Innocenty Popov",
	First = "Innocenty",
	Initials = "IP",
	Last = "Popov",
	LanguageTag = "en-US",
	Maiden = null
};

await graphClient.Me.Profile.Names
	.Request()
	.AddAsync(personName);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const personName = {
  displayName: 'Innocenty Popov',
  first: 'Innocenty',
  initials: 'IP',
  last: 'Popov',
  languageTag: 'en-US',
  maiden: null
};

await client.api('/me/profile/names')
	.version('beta')
	.post(personName);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/profile/names"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

MSGraphPersonName *personName = [[MSGraphPersonName alloc] init];
[personName setDisplayName:@"Innocenty Popov"];
[personName setFirst:@"Innocenty"];
[personName setInitials:@"IP"];
[personName setLast:@"Popov"];
[personName setLanguageTag:@"en-US"];
[personName setMaiden: null];

NSError *error;
NSData *personNameData = [personName getSerializedDataWithError:&error];
[urlRequest setHTTPBody:personNameData];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
	completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

		//Request Completed

}];

[meDataTask execute];

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

PersonName personName = new PersonName();
personName.displayName = "Innocenty Popov";
personName.first = "Innocenty";
personName.initials = "IP";
personName.last = "Popov";
personName.languageTag = "en-US";
personName.maiden = null;

graphClient.me().profile().names()
	.buildRequest()
	.post(personName);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.NewPersonName()
displayName := "Innocenty Popov"
requestBody.SetDisplayName(&displayName)
first := "Innocenty"
requestBody.SetFirst(&first)
initials := "IP"
requestBody.SetInitials(&initials)
last := "Popov"
requestBody.SetLast(&last)
languageTag := "en-US"
requestBody.SetLanguageTag(&languageTag)
requestBody.SetMaiden(nil)
result, err := graphClient.Me().Profile().Names().Post(requestBody)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.People

$params = @{
	DisplayName = "Innocenty Popov"
	First = "Innocenty"
	Initials = "IP"
	Last = "Popov"
	LanguageTag = "en-US"
	Maiden = $null
}

# A UPN can also be used as -UserId.
New-MgUserProfileName -UserId $userId -BodyParameter $params

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

Read the SDK documentation for details about how to add the SDK to your project and create an authProvider instance.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "0fb4c1e3-c1e3-0fb4-e3c1-b40fe3c1b40f",
  "allowedAudiences": "organization",
  "inference": null,
  "createdDateTime": "2020-07-06T06:34:12.2294868Z",
  "createdBy": {
    "application": null,
    "device": null,
    "user": {
      "displayName": "Innocenty Popov",
      "id": "db789417-4ccb-41d1-a0a9-47b01a09ea49"
    }
  },
  "lastModifiedDateTime": "2020-07-06T06:34:12.2294868Z",
  "lastModifiedBy": {
    "application": null,
    "device": null,
    "user": {
      "displayName": "Innocenty Popov",
      "id": "db789417-4ccb-41d1-a0a9-47b01a09ea49"
    }
  },
  "displayName": "Innocenty Popov",
  "first": "Innocenty",
  "initials": "IP",
  "last": "Popov",
  "languageTag": "en-US",
  "maiden": null,
  "middle": null,
  "nickname": null,
  "suffix": null,
  "title": null,
  "pronunciation": null
}