Microsoft Users API

openapi: 3.2.0
info:
  title: Microsoft Graph Users API
  description: Unified API endpoint for accessing Microsoft 365 services including users, groups, mail, calendar, files, and teams. Microsoft Graph provides a single endpoint (https://graph.microsoft.com) to access data and intelligence from Microsoft cloud services.
  version: '1.0'
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
  license:
    name: Microsoft API License
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 (General Availability)
- url: https://graph.microsoft.com/beta
  description: Microsoft Graph Beta (Preview)
security:
- oauth2: []
tags:
- name: Users
  description: Manage Microsoft Entra user accounts and profiles
paths:
  /users:
    get:
      operationId: listUsers
      summary: Microsoft List users
      description: Retrieve a list of user objects. By default, only a limited set of properties are returned. To return an alternative property set, specify the desired properties using the OData $select query parameter.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: Collection of user objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  '@odata.nextLink':
                    type: string
                    description: URL to retrieve the next page of results
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createUser
      summary: Microsoft Create user
      description: Create a new user object. The request body contains the user to create. At a minimum, you must specify the required properties for the user, including displayName, mailNickname, userPrincipalName, and passwordProfile.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{user-id}:
    get:
      operationId: getUser
      summary: Microsoft Get user
      description: Retrieve the properties and relationships of a user object. Returns a default set of properties unless you use $select to specify specific properties.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateUser
      summary: Microsoft Update user
      description: Update the properties of a user object. Not all properties can be updated by Member or Guest users with their default permissions.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '204':
          description: User updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      summary: Microsoft Delete user
      description: Delete a user object. When deleted, user resources are moved to a temporary container and can be restored within 30 days. After that time, they are permanently deleted.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '204':
          description: User deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{user-id}/manager:
    get:
      operationId: getUserManager
      summary: Microsoft Get user's manager
      description: Returns the user or organizational contact assigned as the user's manager. Optionally, you can expand the manager's chain up to the root node.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: Manager directory object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{user-id}/directReports:
    get:
      operationId: listUserDirectReports
      summary: Microsoft List user's direct reports
      description: Get the users and organizational contacts that report to the user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/top'
      responses:
        '200':
          description: Collection of direct reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{user-id}/memberOf:
    get:
      operationId: listUserMemberOf
      summary: Microsoft List user's group memberships
      description: Get the groups, directory roles, and administrative units that the user is a direct member of.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Collection of directory objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryObject'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    count:
      name: $count
      in: query
      required: false
      description: Include count of items in the response
      schema:
        type: boolean
    userId:
      name: user-id
      in: path
      required: true
      description: Unique identifier of the user (GUID or userPrincipalName)
      schema:
        type: string
    top:
      name: $top
      in: query
      required: false
      description: Number of items to return (page size)
      schema:
        type: integer
        minimum: 1
    filter:
      name: $filter
      in: query
      required: false
      description: OData filter expression
      schema:
        type: string
    search:
      name: $search
      in: query
      required: false
      description: Search expression to filter results
      schema:
        type: string
    skip:
      name: $skip
      in: query
      required: false
      description: Number of items to skip for pagination
      schema:
        type: integer
        minimum: 0
    orderby:
      name: $orderby
      in: query
      required: false
      description: OData order by expression
      schema:
        type: string
    select:
      name: $select
      in: query
      required: false
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
  schemas:
    DirectoryObject:
      type: object
      properties:
        '@odata.type':
          type: string
          description: OData type annotation
        id:
          type: string
          description: Unique identifier (GUID)
        deletedDateTime:
          type: string
          format: date-time
          description: Date and time when object was deleted
    UserCreate:
      type: object
      required:
      - accountEnabled
      - displayName
      - mailNickname
      - userPrincipalName
      - passwordProfile
      properties:
        accountEnabled:
          type: boolean
          description: Whether the account is enabled
        displayName:
          type: string
          description: Name displayed in the address book
          maxLength: 256
        mailNickname:
          type: string
          description: Mail alias for the user
          maxLength: 64
        userPrincipalName:
          type: string
          description: User principal name
        passwordProfile:
          type: object
          required:
          - password
          properties:
            forceChangePasswordNextSignIn:
              type: boolean
              description: Whether user must change password on next sign-in
            password:
              type: string
              description: The password for the user
        givenName:
          type: string
          description: First name
        surname:
          type: string
          description: Last name
        jobTitle:
          type: string
          description: Job title
        department:
          type: string
          description: Department
        officeLocation:
          type: string
          description: Office location
        usageLocation:
          type: string
          description: Two-letter country code for license assignment
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user (GUID)
          readOnly: true
        displayName:
          type: string
          description: Name displayed in the address book
          maxLength: 256
        givenName:
          type: string
          description: First name of the user
          maxLength: 64
        surname:
          type: string
          description: Last name of the user
          maxLength: 64
        mail:
          type: string
          format: email
          description: SMTP address for the user
        userPrincipalName:
          type: string
          description: User principal name (UPN) in internet-style login format
        jobTitle:
          type: string
          description: User's job title
          maxLength: 128
        department:
          type: string
          description: Department name
          maxLength: 64
        officeLocation:
          type: string
          description: Office location in the user's place of business
        businessPhones:
          type: array
          items:
            type: string
          description: Telephone numbers for the user
        mobilePhone:
          type: string
          description: Primary cellular telephone number
          maxLength: 64
        city:
          type: string
          description: City where the user is located
          maxLength: 128
        state:
          type: string
          description: State or province in the user's address
          maxLength: 128
        country:
          type: string
          description: Country or region where the user is located
          maxLength: 128
        postalCode:
          type: string
          description: Postal code for the user's postal address
          maxLength: 40
        streetAddress:
          type: string
          description: Street address of the user's place of business
          maxLength: 1024
        companyName:
          type: string
          description: Company name associated with the user
          maxLength: 64
        employeeId:
          type: string
          description: Employee identifier assigned to the user
          maxLength: 16
        employeeType:
          type: string
          description: Captures enterprise worker type (Employee, Contractor, etc.)
        accountEnabled:
          type: boolean
          description: Whether the account is enabled
        createdDateTime:
          type: string
          format: date-time
          description: Date and time the user was created
          readOnly: true
        lastPasswordChangeDateTime:
          type: string
          format: date-time
          description: Time of last password change
          readOnly: true
        preferredLanguage:
          type: string
          description: Preferred language for the user (ISO 639-1 code)
        usageLocation:
          type: string
          description: Two-letter country code required for license assignment
        mailNickname:
          type: string
          description: Mail alias for the user
          maxLength: 64
        proxyAddresses:
          type: array
          items:
            type: string
          description: Email addresses that direct to the same mailbox
          readOnly: true
        onPremisesSyncEnabled:
          type: boolean
          description: Whether the user is synced from on-premises AD
          readOnly: true
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            innerError:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                request-id:
                  type: string
                client-request-id:
                  type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized - authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request - invalid input or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: Microsoft identity platform OAuth 2.0 authorization
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            User.Read: Read the signed-in user's profile
            User.ReadWrite: Read and update the signed-in user's profile
            User.Read.All: Read all users' full profiles
            User.ReadWrite.All: Read and write all users' full profiles
            Group.Read.All: Read all groups
            Group.ReadWrite.All: Read and write all groups
            Mail.Read: Read user mail
            Mail.ReadWrite: Read and write user mail
            Mail.Send: Send mail as a user
            Calendars.Read: Read user calendars
            Calendars.ReadWrite: Read and write user calendars
            Files.Read: Read user files
            Files.ReadWrite: Read and write user files
            Files.Read.All: Read all files that user can access
            Team.ReadBasic.All: Read the names and descriptions of teams
            Channel.ReadBasic.All: Read channel names and descriptions
            ChannelMessage.Read.All: Read all channel messages
            ChannelMessage.Send: Send channel messages
            Application.Read.All: Read all applications
            Application.ReadWrite.All: Read and write all applications
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            https://graph.microsoft.com/.default: Default scope for application permissions
externalDocs:
  description: Microsoft Graph API Documentation
  url: https://learn.microsoft.com/en-us/graph/overview