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.
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.
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.
// 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);
<?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);
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.
// 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);
<?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);