Edit

Share via

Create agentUser

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.

Create a new agentUser object. You can also create an agent user by using the POST /users endpoint and specifying the microsoft.graph.agentUser type in the request body.

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 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.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ✅ ✅ ✅

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

Important

The AgentIdentity* permissions are currently unavailable for consent through the API permissions experience on the Microsoft Entra admin center. To use these permissions, you can consent to them through Microsoft Graph API calls as described in Grant or revoke API permissions programmatically. See Permissions for managing agent identities for more information about these permissions.

In delegated scenarios with work or school accounts, the admin must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. The following least privileged roles are supported for this operation.

  • Agent ID Administrator

HTTP request

POST /users/microsoft.graph.agentUser

Tip

You can also create agent users through the POST /users without specifying the microsoft.graph.agentUser type. However, "@odata.type": "microsoft.graph.agentUser" must be specified in the request body together with other required properties for user creation.

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 agentUser object.

The following table lists the properties that are required when you create an agentUser.

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 agent user.
mailNickname String The mail alias for the agent user.
userPrincipalName String The user principal name (someagent@contoso.com). It's an Internet-style login name for the agent user based on the Internet standard RFC 822. By convention, this should map to the agent 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.

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

Response

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

Attempting to create an agentUser with an identityParentId already linked to another agentUser returns a 400 Bad Request error.

Examples

Request

The following example shows a request.

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

{
  "accountEnabled": true,
  "displayName": "Sales Agent",
  "mailNickname": "SalesAgent",
  "userPrincipalName": "salesagent@contoso.com",
  "identityParentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

The following example shows the response.

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": "Sales Agent",
    "mail": "salesagent@contoso.com",
    "mailNickname": "SalesAgent",
    "userPrincipalName": "salesagent@contoso.com",
    "identityParentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Related content

  • Last updated on