title	Create user
description	Create a new user.
author	yyuank
ms.reviewer	iamut
ms.localizationpriority	medium
ms.subservice	entra-users
doc_type	apiPageType
ms.date	10/22/2024

Create user

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

Create a new user. If you specify an @odata.type property with a value of #microsoft.graph.agentUser with the required properties, this API creates an agentUser object.

At a minimum, you must specify the required properties. You can optionally specify any other writable properties.

This operation returns by default only a subset of the properties for each user and agentUser. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.

Note

To create external users as part of B2B collaboration with your organization, use the invitation API. To create a customer, citizen, or business partner in Microsoft Entra External ID in external tenants, see Example 4: Create a customer account.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permission	Higher privileged permissions
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. Learn more about authentication and authorization.
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 or agentUser.

You must specify an @odata.type property with a value of #microsoft.graph.agentUser to create an agentUser, otherwise a user is created and the iden
If you're including an identities property for the user you're creating, not all the properties listed are required. 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	Required only 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. Applies to user only and not allowed for agentUser.
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.
identityParentId	String	The object ID of the associated agent identity. Required for agentUser where @odata.type of `#microsoft.graph.agentUser` must be set and ignored for regular users. If not set, a regular user is created.

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

Federated users created via this API must sign in every 12 hours by default. For information about how to change this, see Exceptions for token lifetimes.

Note

Adding a B2C local account to an existing user object is not allowed, unless the user object already contains a local account identity.

Response

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

Omitting the @odata.type property of #microsoft.graph.agentUser creates a user object, even if the identityParentId is specified. Attempting to create an agentUser with a identityParentId already linked to another agentUser returns a 400 Bad Request error.

Example

Example 1: Create a user

Request

The following example shows a request, specifying only the required properties.

HTTP

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

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows 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/beta/$metadata#users/$entity",
    "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "businessPhones": [],
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "jobTitle": "Product Marketing Manager",
    "mail": "AdeleV@contoso.com",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "AdeleV@contoso.com"
}

Example 2: Create an agent user

Request

The following example shows a request, specifying only the required properties.

HTTP

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

{
  "@odata.type": "#microsoft.graph.agentUser",
  "accountEnabled": true,
  "displayName": "Adele Vance",
  "mailNickname": "AdeleV",
  "userPrincipalName": "AdeleV@contoso.com",
  "identityParentId": ""
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows 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/beta/$metadata#users/$entity",
    "@odata.type": "#microsoft.graph.agentUser",
    "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "businessPhones": [],
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "jobTitle": "Product Marketing Manager",
    "mail": "AdeleV@contoso.com",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "AdeleV@contoso.com"
}

Example 3: Create a user with social and local account identities in Azure AD B2C

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 Azure AD 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/beta/users
Content-type: application/json

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows 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/beta/$metadata#users/$entity",
  "displayName": "John Smith",
  "id": "4c7be08b-361f-41a8-b1ef-1712f7a3dfb2",
  "identities": [
    {
      "signInType": "userName",
      "issuer": "contoso.com",
      "issuerAssignedId": "johnsmith"
    },
    {
      "signInType": "emailAddress",
      "issuer": "contoso.com",
      "issuerAssignedId": "jsmith@yahoo.com"
    },
    {
      "signInType": "federated",
      "issuer": "facebook.com",
      "issuerAssignedId": "5eecb0cd"
    }
  ],
  "passwordPolicies": "DisablePasswordExpiration"
}

Example 4: Create a customer account in external tenants

This example shows how to create a customer account in Microsoft Entra External ID in external tenants.

Note

For local account identities, password expirations must be disabled.

Request

HTTP

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

{
    "displayName": "Test User",
    "identities": [
        {
            "signInType": "emailAddress",
            "issuer": "contoso.onmicrosoft.com",
            "issuerAssignedId": "adelev@adatum.com"
        }
    ],
    "mail": "adelev@adatum.com",
    "passwordProfile": {
        "password": "passwordValue",
        "forceChangePasswordNextSignIn": true
    },
    "passwordPolicies": "DisablePasswordExpiration"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows 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/beta/$metadata#users/$entity",
    "id": "daabd280-3978-4d29-acce-d677b9cf2e4d",
    "businessPhones": [],
    "displayName": "Test User",
    "givenName": null,
    "jobTitle": null,
    "mail": "adelev@adatum.com",
    "mobilePhone": null,
    "officeLocation": null,
    "preferredLanguage": null,
    "surname": null,
    "userPrincipalName": "daabd280-3978-4d29-acce-d677b9cf2e4d@contoso.onmicrosoft.com"
}

FilesExpand file tree

user-post-users.md

Latest commit

History

user-post-users.md

File metadata and controls

Create user

Permissions

HTTP request

Request headers

Request body

Response

Example

Example 1: Create a user

Request

Response

Example 2: Create an agent user

Request

Response

Example 3: Create a user with social and local account identities in Azure AD B2C

Request

Response

Example 4: Create a customer account in external tenants

Request

Response

Related content