Create User

Use this API to 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 scopes is required to execute this API: User.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.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 shows the properties that are required when you create a user.

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 (


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



Here is an example of the request.

Content-type: application/json

  "accountEnabled": true,
  "displayName": "displayName-value",
  "mailNickname": "mailNickname-value",
  "userPrincipalName": "",
  "passwordProfile" : {
    "forceChangePasswordNextSignIn": true,
    "password": "password-value"

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


Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

    "@odata.context": "$metadata#users/$entity",
    "id": "id-value",
    "businessPhones": [],
    "displayName": "displayName-value",
    "givenName": null,
    "jobTitle": null,
    "mail": null,
    "mobilePhone": null,
    "officeLocation": null,
    "preferredLanguage": null,
    "surname": null,
    "userPrincipalName": ""