Skip to main content

​
Overview

The Users API provides operations to manage user entities in Azure Active Directory. Access through graphClient.Users.

​
Request Builder

public UsersRequestBuilder Users { get; }
Accessed via: graphClient.Users

​
Operations

​
List Users

Retrieve a list of user objects. 
public async Task<UserCollectionResponse> GetAsync(
    Action<RequestConfiguration<UsersRequestBuilderGetQueryParameters>> requestConfiguration = default,
    CancellationToken cancellationToken = default
)
Query Parameters:
​
$select
string[]
Properties to include in response (e.g., ["id", "displayName", "mail"])
​
$filter
string
Filter expression (e.g., "startsWith(displayName,'John')", "accountEnabled eq true")
​
$orderby
string[]
Sort order (e.g., ["displayName"], ["createdDateTime desc"])
​
$top
int
Number of items to return (max 999)
​
$search
string
Search query (requires ConsistencyLevel: eventual header)
​
$count
bool
Include count of items in response
​
$expand
string[]
Related entities to expand (e.g., ["manager"], ["memberOf"])
Response:
​
value
User[]
Array of user objects
​
@odata.nextLink
string
URL for next page of results (if paginated)
Example: 
// Get all users
var users = await graphClient.Users.GetAsync();

foreach (var user in users.Value)
{
    Console.WriteLine($"{user.DisplayName} - {user.Mail}");
}

// Filter users
var activeUsers = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Filter = "accountEnabled eq true";
    config.QueryParameters.Select = new[] { "id", "displayName", "mail" };
    config.QueryParameters.Top = 100;
});

// Search users (requires ConsistencyLevel header)
var searchResults = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Search = "\"displayName:John\"";
    config.QueryParameters.Count = true;
    config.Headers.Add("ConsistencyLevel", "eventual");
});

​
Create User

Create a new user account. 
public async Task<User> PostAsync(
    User body,
    Action<RequestConfiguration<DefaultQueryParameters>> requestConfiguration = default,
    CancellationToken cancellationToken = default
)
​
body
User
required
User object with required properties
Required Properties:
  • AccountEnabled - Enable or disable the account
  • DisplayName - User’s display name
  • MailNickname - Email alias
  • UserPrincipalName - User’s sign-in name
  • PasswordProfile - Password settings (for password authentication)
Example: 
var newUser = new User
{
    AccountEnabled = true,
    DisplayName = "John Doe",
    MailNickname = "johnd",
    UserPrincipalName = "[email protected]",
    PasswordProfile = new PasswordProfile
    {
        ForceChangePasswordNextSignIn = true,
        Password = "TempPassword123!"
    },
    Department = "Engineering",
    JobTitle = "Software Engineer"
};

var user = await graphClient.Users.PostAsync(newUser);
Console.WriteLine($"Created user: {user.Id}");

​
Get User by ID

Retrieve a specific user by their ID. 
var user = await graphClient.Users["user-id"].GetAsync();

// Select specific properties
var user = await graphClient.Users["user-id"].GetAsync(config =>
{
    config.QueryParameters.Select = new[] { "id", "displayName", "mail", "jobTitle" };
});

​
Update User

Update user properties. 
var userToUpdate = new User
{
    JobTitle = "Senior Software Engineer",
    Department = "Engineering - Cloud",
    MobilePhone = "+1 555-0123"
};

await graphClient.Users["user-id"].PatchAsync(userToUpdate);

​
Delete User

Delete a user account. 
await graphClient.Users["user-id"].DeleteAsync();

​
Additional Methods

​
Delta Query

Get incremental changes to users. 
var deltaResponse = await graphClient.Users.Delta.GetAsync();

// Process users
foreach (var user in deltaResponse.Value)
{
    Console.WriteLine($"Changed user: {user.DisplayName}");
}

// Get next delta
if (deltaResponse.OdataDeltaLink != null)
{
    // Store deltaLink for next query
}

​
Get by IDs

Retrieve multiple users by their IDs. 
var requestBody = new GetByIdsPostRequestBody
{
    Ids = new List<string>
    {
        "user-id-1",
        "user-id-2",
        "user-id-3"
    },
    Types = new List<string> { "user" }
};

var users = await graphClient.Users.GetByIds.PostAsync(requestBody);

​
Count Users

var count = await graphClient.Users.Count.GetAsync();
Console.WriteLine($"Total users: {count}");

​
User Item Operations

Access nested resources for a specific user: 
var userId = "user-id";
var userBuilder = graphClient.Users[userId];

// Messages
var messages = await userBuilder.Messages.GetAsync();

// Calendar
var calendar = await userBuilder.Calendar.GetAsync();

// Events
var events = await userBuilder.Events.GetAsync();

// Drive
var drive = await userBuilder.Drive.GetAsync();

// Manager
var manager = await userBuilder.Manager.GetAsync();

// Direct reports
var reports = await userBuilder.DirectReports.GetAsync();

// Member of (groups)
var groups = await userBuilder.MemberOf.GetAsync();

// Send mail
var message = new Message
{
    Subject = "Test",
    Body = new ItemBody { Content = "Hello", ContentType = BodyType.Text },
    ToRecipients = new[] { new Recipient { EmailAddress = new EmailAddress { Address = "[email protected]" } } }
};
await userBuilder.SendMail.PostAsync(new SendMailPostRequestBody { Message = message });

​
Common Filtering Examples

// Users in a department
config.QueryParameters.Filter = "department eq 'Sales'";

// Users created after a date
config.QueryParameters.Filter = "createdDateTime ge 2024-01-01T00:00:00Z";

// Users with a specific domain
config.QueryParameters.Filter = "endsWith(mail,'@contoso.com')";

// Active external users
config.QueryParameters.Filter = "accountEnabled eq true and userType eq 'Guest'";

// Users without a manager
config.QueryParameters.Filter = "manager/id eq null";

​
Pagination

Handle large result sets: 
var allUsers = new List<User>();
var response = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Top = 100;
});

allUsers.AddRange(response.Value);

while (response.OdataNextLink != null)
{
    response = await graphClient.Users
        .WithUrl(response.OdataNextLink)
        .GetAsync();
    allUsers.AddRange(response.Value);
}

​
Error Handling

using Microsoft.Graph.Models.ODataErrors;

try
{
    var user = await graphClient.Users["invalid-id"].GetAsync();
}
catch (ODataError error)
{
    Console.WriteLine($"Error: {error.Error.Code}");
    Console.WriteLine($"Message: {error.Error.Message}");
}

​
See Also

User Model

User resource properties

Messages API

User messages operations

Calendar API

User calendar operations

Groups API

Group management

Build docs developers (and LLMs) love

Get started for freeTalk to us