Create User

Namespace: microsoft.graph

Create a new user. The request body contains the user to create. At a minimum, you must specify the required properties for the user. You can optionally specify any other writable properties.

Note

To create external users, use the invitation API.

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.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	User.ReadWrite.All, Directory.ReadWrite.All

HTTP request

POST /users

Request headers

Header	Value
Authorization	Bearer {token}. Required.
Content-Type	application/json

Request body

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

The following table lists the properties that are required when you create a user. If you're including an identities property for the user you're creating, not all the properties listed are required. For a B2C local account identity, only passwordProfile is required, and passwordPolicies must be set to DisablePasswordExpiration. For a social identity, none of the properties are required.

Parameter	Type	Description
accountEnabled	boolean	true if the account is enabled; otherwise, false.
displayName	string	The name to display in the address book for the user.
onPremisesImmutableId	string	Only needs to be specified when creating a new user account if you are using a federated domain for the user's userPrincipalName (UPN) property.
mailNickname	string	The mail alias for the user.
passwordProfile	PasswordProfile	The password profile for the user.
userPrincipalName	string	The user principal name (someuser@contoso.com). It's an Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is alias@domain, where domain must be present in the tenant's collection of verified domains. The verified domains for the tenant can be accessed from the verifiedDomains property of organization. NOTE: This property cannot contain accent characters. Only the following characters are allowed A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. For the complete list of allowed characters, see username policies.

Because the user resource supports extensions, you can use the POST operation and add custom properties with your own data to the user instance while creating it.

Note

Federated users created using this API will be forced to sign-in every 12 hours by default. For more information on how to change this, see Exceptions for token lifetimes.

Response

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

Example

Example 1: Create a user

Request

Here is an example of the request.

HTTP

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
  "accountEnabled": true,
  "displayName": "Adele Vance",
  "mailNickname": "AdeleV",
  "userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
  "passwordProfile" : {
    "forceChangePasswordNextSignIn": true,
    "password": "xWwvJ]6NMw+bWH-d"
  }
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new User
{
	AccountEnabled = true,
	DisplayName = "Adele Vance",
	MailNickname = "AdeleV",
	UserPrincipalName = "AdeleV@contoso.onmicrosoft.com",
	PasswordProfile = new PasswordProfile
	{
		ForceChangePasswordNextSignIn = true,
		Password = "xWwvJ]6NMw+bWH-d",
	},
};
var result = await graphClient.Users.PostAsync(requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewUser()
accountEnabled := true
requestBody.SetAccountEnabled(&accountEnabled) 
displayName := "Adele Vance"
requestBody.SetDisplayName(&displayName) 
mailNickname := "AdeleV"
requestBody.SetMailNickname(&mailNickname) 
userPrincipalName := "AdeleV@contoso.onmicrosoft.com"
requestBody.SetUserPrincipalName(&userPrincipalName) 
passwordProfile := graphmodels.NewPasswordProfile()
forceChangePasswordNextSignIn := true
passwordProfile.SetForceChangePasswordNextSignIn(&forceChangePasswordNextSignIn) 
password := "xWwvJ]6NMw+bWH-d"
passwordProfile.SetPassword(&password) 
requestBody.SetPasswordProfile(passwordProfile)

result, err := graphClient.Users().Post(context.Background(), requestBody, nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

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

User user = new User();
user.accountEnabled = true;
user.displayName = "Adele Vance";
user.mailNickname = "AdeleV";
user.userPrincipalName = "AdeleV@contoso.onmicrosoft.com";
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.forceChangePasswordNextSignIn = true;
passwordProfile.password = "xWwvJ]6NMw+bWH-d";
user.passwordProfile = passwordProfile;

graphClient.users()
	.buildRequest()
	.post(user);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const user = {
  accountEnabled: true,
  displayName: 'Adele Vance',
  mailNickname: 'AdeleV',
  userPrincipalName: 'AdeleV@contoso.onmicrosoft.com',
  passwordProfile: {
    forceChangePasswordNextSignIn: true,
    password: 'xWwvJ]6NMw+bWH-d'
  }
};

await client.api('/users')
	.post(user);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new User();
$requestBody->setAccountEnabled(true);

$requestBody->setDisplayName('Adele Vance');

$requestBody->setMailNickname('AdeleV');

$requestBody->setUserPrincipalName('AdeleV@contoso.onmicrosoft.com');

$passwordProfile = new PasswordProfile();
$passwordProfile->setForceChangePasswordNextSignIn(true);

$passwordProfile->setPassword('xWwvJ]6NMw+bWH-d');


$requestBody->setPasswordProfile($passwordProfile);


$result = $graphServiceClient->users()->post($requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

$params = @{
	accountEnabled = $true
	displayName = "Adele Vance"
	mailNickname = "AdeleV"
	userPrincipalName = "AdeleV@contoso.onmicrosoft.com"
	passwordProfile = @{
		forceChangePasswordNextSignIn = $true
		password = "xWwvJ]6NMw+bWH-d"
	}
}

New-MgUser -BodyParameter $params

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

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

Response

Here 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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "businessPhones": [],
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "jobTitle": "Product Marketing Manager",
    "mail": "AdeleV@contoso.onmicrosoft.com",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "AdeleV@contoso.onmicrosoft.com"
}

Example 2: Create a user with social and local account identities

Create a new user, with a local account identity with a sign-in name, an email address as sign-in, and with a social identity. This example is typically used for migration scenarios in B2C tenants.

Note

For local account identities, password expirations must be disabled, and force change password at next sign-in must also be disabled.

Request

HTTP

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
  "displayName": "John Smith",
  "identities": [
    {
      "signInType": "userName",
      "issuer": "contoso.onmicrosoft.com",
      "issuerAssignedId": "johnsmith"
    },
    {
      "signInType": "emailAddress",
      "issuer": "contoso.onmicrosoft.com",
      "issuerAssignedId": "jsmith@yahoo.com"
    },
    {
      "signInType": "federated",
      "issuer": "facebook.com",
      "issuerAssignedId": "5eecb0cd"
    }
  ],
  "passwordProfile" : {
    "password": "password-value",
    "forceChangePasswordNextSignIn": false
  },
  "passwordPolicies": "DisablePasswordExpiration"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new User
{
	DisplayName = "John Smith",
	Identities = new List<ObjectIdentity>
	{
		new ObjectIdentity
		{
			SignInType = "userName",
			Issuer = "contoso.onmicrosoft.com",
			IssuerAssignedId = "johnsmith",
		},
		new ObjectIdentity
		{
			SignInType = "emailAddress",
			Issuer = "contoso.onmicrosoft.com",
			IssuerAssignedId = "jsmith@yahoo.com",
		},
		new ObjectIdentity
		{
			SignInType = "federated",
			Issuer = "facebook.com",
			IssuerAssignedId = "5eecb0cd",
		},
	},
	PasswordProfile = new PasswordProfile
	{
		Password = "password-value",
		ForceChangePasswordNextSignIn = false,
	},
	PasswordPolicies = "DisablePasswordExpiration",
};
var result = await graphClient.Users.PostAsync(requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewUser()
displayName := "John Smith"
requestBody.SetDisplayName(&displayName) 


objectIdentity := graphmodels.NewObjectIdentity()
signInType := "userName"
objectIdentity.SetSignInType(&signInType) 
issuer := "contoso.onmicrosoft.com"
objectIdentity.SetIssuer(&issuer) 
issuerAssignedId := "johnsmith"
objectIdentity.SetIssuerAssignedId(&issuerAssignedId) 
objectIdentity1 := graphmodels.NewObjectIdentity()
signInType := "emailAddress"
objectIdentity1.SetSignInType(&signInType) 
issuer := "contoso.onmicrosoft.com"
objectIdentity1.SetIssuer(&issuer) 
issuerAssignedId := "jsmith@yahoo.com"
objectIdentity1.SetIssuerAssignedId(&issuerAssignedId) 
objectIdentity2 := graphmodels.NewObjectIdentity()
signInType := "federated"
objectIdentity2.SetSignInType(&signInType) 
issuer := "facebook.com"
objectIdentity2.SetIssuer(&issuer) 
issuerAssignedId := "5eecb0cd"
objectIdentity2.SetIssuerAssignedId(&issuerAssignedId) 

identities := []graphmodels.ObjectIdentityable {
	objectIdentity,
	objectIdentity1,
	objectIdentity2,

}
requestBody.SetIdentities(identities)
passwordProfile := graphmodels.NewPasswordProfile()
password := "password-value"
passwordProfile.SetPassword(&password) 
forceChangePasswordNextSignIn := false
passwordProfile.SetForceChangePasswordNextSignIn(&forceChangePasswordNextSignIn) 
requestBody.SetPasswordProfile(passwordProfile)
passwordPolicies := "DisablePasswordExpiration"
requestBody.SetPasswordPolicies(&passwordPolicies) 

result, err := graphClient.Users().Post(context.Background(), requestBody, nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

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

User user = new User();
user.displayName = "John Smith";
LinkedList<ObjectIdentity> identitiesList = new LinkedList<ObjectIdentity>();
ObjectIdentity identities = new ObjectIdentity();
identities.signInType = "userName";
identities.issuer = "contoso.onmicrosoft.com";
identities.issuerAssignedId = "johnsmith";
identitiesList.add(identities);
ObjectIdentity identities1 = new ObjectIdentity();
identities1.signInType = "emailAddress";
identities1.issuer = "contoso.onmicrosoft.com";
identities1.issuerAssignedId = "jsmith@yahoo.com";
identitiesList.add(identities1);
ObjectIdentity identities2 = new ObjectIdentity();
identities2.signInType = "federated";
identities2.issuer = "facebook.com";
identities2.issuerAssignedId = "5eecb0cd";
identitiesList.add(identities2);
user.identities = identitiesList;
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.password = "password-value";
passwordProfile.forceChangePasswordNextSignIn = false;
user.passwordProfile = passwordProfile;
user.passwordPolicies = "DisablePasswordExpiration";

graphClient.users()
	.buildRequest()
	.post(user);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const user = {
  displayName: 'John Smith',
  identities: [
    {
      signInType: 'userName',
      issuer: 'contoso.onmicrosoft.com',
      issuerAssignedId: 'johnsmith'
    },
    {
      signInType: 'emailAddress',
      issuer: 'contoso.onmicrosoft.com',
      issuerAssignedId: 'jsmith@yahoo.com'
    },
    {
      signInType: 'federated',
      issuer: 'facebook.com',
      issuerAssignedId: '5eecb0cd'
    }
  ],
  passwordProfile: {
    password: 'password-value',
    forceChangePasswordNextSignIn: false
  },
  passwordPolicies: 'DisablePasswordExpiration'
};

await client.api('/users')
	.post(user);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new User();
$requestBody->setDisplayName('John Smith');

$identitiesObjectIdentity1 = new ObjectIdentity();
$identitiesObjectIdentity1->setSignInType('userName');

$identitiesObjectIdentity1->setIssuer('contoso.onmicrosoft.com');

$identitiesObjectIdentity1->setIssuerAssignedId('johnsmith');


$identitiesArray []= $identitiesObjectIdentity1;
$identitiesObjectIdentity2 = new ObjectIdentity();
$identitiesObjectIdentity2->setSignInType('emailAddress');

$identitiesObjectIdentity2->setIssuer('contoso.onmicrosoft.com');

$identitiesObjectIdentity2->setIssuerAssignedId('jsmith@yahoo.com');


$identitiesArray []= $identitiesObjectIdentity2;
$identitiesObjectIdentity3 = new ObjectIdentity();
$identitiesObjectIdentity3->setSignInType('federated');

$identitiesObjectIdentity3->setIssuer('facebook.com');

$identitiesObjectIdentity3->setIssuerAssignedId('5eecb0cd');


$identitiesArray []= $identitiesObjectIdentity3;
$requestBody->setIdentities($identitiesArray);


$passwordProfile = new PasswordProfile();
$passwordProfile->setPassword('password-value');

$passwordProfile->setForceChangePasswordNextSignIn(false);


$requestBody->setPasswordProfile($passwordProfile);
$requestBody->setPasswordPolicies('DisablePasswordExpiration');



$result = $graphServiceClient->users()->post($requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

$params = @{
	displayName = "John Smith"
	identities = @(
		@{
			signInType = "userName"
			issuer = "contoso.onmicrosoft.com"
			issuerAssignedId = "johnsmith"
		}
		@{
			signInType = "emailAddress"
			issuer = "contoso.onmicrosoft.com"
			issuerAssignedId = "jsmith@yahoo.com"
		}
		@{
			signInType = "federated"
			issuer = "facebook.com"
			issuerAssignedId = "5eecb0cd"
		}
	)
	passwordProfile = @{
		password = "password-value"
		forceChangePasswordNextSignIn = $false
	}
	passwordPolicies = "DisablePasswordExpiration"
}

New-MgUser -BodyParameter $params

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here 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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "displayName": "John Smith",
  "id": "4c7be08b-361f-41a8-b1ef-1712f7a3dfb2",
  "identities": [
    {
      "signInType": "userName",
      "issuer": "contoso.onmicrosoft.com",
      "issuerAssignedId": "johnsmith"
    },
    {
      "signInType": "emailAddress",
      "issuer": "contoso.onmicrosoft.com",
      "issuerAssignedId": "jsmith@yahoo.com"
    },
    {
      "signInType": "federated",
      "issuer": "facebook.com",
      "issuerAssignedId": "5eecb0cd"
    }
  ],
  "passwordPolicies": "DisablePasswordExpiration"
}

See also

• Add custom data to resources using extensions
• Add custom data to users using open extensions