Microsoft Office 365 Users API

openapi: 3.1.0
info:
  title: Microsoft Office 365 Microsoft Graph Calendar Users API
  description: The Microsoft Graph API provides a unified programmability model to access data, intelligence, and insights from Microsoft 365, Windows, and Enterprise Mobility + Security. It serves as the gateway to data and intelligence in Microsoft 365, enabling applications to interact with users, groups, mail, calendars, files, and other organizational resources through a single REST endpoint.
  version: 1.0.0
  termsOfService: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  license:
    name: Microsoft API License
    url: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-documentation:
    url: https://learn.microsoft.com/en-us/graph/overview
  x-api-explorer:
    url: https://developer.microsoft.com/en-us/graph/graph-explorer
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
- url: https://graph.microsoft.com/beta
  description: Microsoft Graph beta endpoint (preview features)
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Users
  description: Manage users in Azure Active Directory. Users are the core identity resource representing a person, including their profile, organizational relationships, and access to services.
  externalDocs:
    url: https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0
paths:
  /users:
    get:
      operationId: listUsers
      summary: Microsoft Office 365 List Users
      description: Retrieve a list of user objects. By default, only a limited set of properties are returned. To return additional properties, use the $select OData query parameter. Returns up to 100 users per page by default. Requires User.ReadBasic.All, User.Read.All, or Directory.Read.All permission.
      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'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A collection of user objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCollectionResponse'
              examples:
                Listusers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    '@odata.context': example_value
                    '@odata.count': 10
                    '@odata.nextLink': https://www.example.com
                    value:
                    - id: abc123
                      displayName: example_value
                      givenName: example_value
                      surname: example_value
                      mail: example_value
                      userPrincipalName: example_value
                      jobTitle: example_value
                      department: example_value
                      officeLocation: example_value
                      companyName: example_value
                      businessPhones: {}
                      mobilePhone: example_value
                      streetAddress: example_value
                      city: example_value
                      state: example_value
                      postalCode: example_value
                      country: example_value
                      preferredLanguage: example_value
                      accountEnabled: true
                      createdDateTime: '2026-01-15T10:30:00Z'
                      lastSignInDateTime: '2026-01-15T10:30:00Z'
                      usageLocation: example_value
                      identities: {}
                      assignedLicenses: {}
                      memberOf: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createUser
      summary: Microsoft Office 365 Create User
      description: Create a new user object. The request body must contain the required properties for the user. You can optionally specify other writable properties. Requires User.ReadWrite.All or Directory.ReadWrite.All permission.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
            examples:
              CreateuserRequestExample:
                summary: Default createUser request
                x-microcks-default: true
                value:
                  accountEnabled: true
                  displayName: example_value
                  mailNickname: example_value
                  userPrincipalName: example_value
                  passwordProfile:
                    forceChangePasswordNextSignIn: true
                    forceChangePasswordNextSignInWithMfa: true
                    password: example_value
                  givenName: example_value
                  surname: example_value
                  jobTitle: example_value
                  department: example_value
                  officeLocation: example_value
                  mobilePhone: example_value
                  usageLocation: example_value
      responses:
        '201':
          description: The created user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Createuser201Example:
                  summary: Default createUser 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    displayName: example_value
                    givenName: example_value
                    surname: example_value
                    mail: example_value
                    userPrincipalName: example_value
                    jobTitle: example_value
                    department: example_value
                    officeLocation: example_value
                    companyName: example_value
                    businessPhones:
                    - example_value
                    mobilePhone: example_value
                    streetAddress: example_value
                    city: example_value
                    state: example_value
                    postalCode: example_value
                    country: example_value
                    preferredLanguage: example_value
                    accountEnabled: true
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastSignInDateTime: '2026-01-15T10:30:00Z'
                    usageLocation: example_value
                    passwordProfile:
                      forceChangePasswordNextSignIn: true
                      forceChangePasswordNextSignInWithMfa: true
                      password: example_value
                    identities:
                    - signInType: example_value
                      issuer: example_value
                      issuerAssignedId: '500123'
                    assignedLicenses:
                    - disabledPlans: {}
                      skuId: '500123'
                    manager:
                      '@odata.type': example_value
                      id: abc123
                      displayName: example_value
                    memberOf:
                    - '@odata.type': example_value
                      id: abc123
                      displayName: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user-id}:
    get:
      operationId: getUser
      summary: Microsoft Office 365 Get User
      description: Retrieve the properties and relationships of a user object. Returns a limited set of properties by default; use $select to request additional properties. Requires User.Read, User.ReadBasic.All, User.Read.All, or Directory.Read.All permission.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Getuser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    displayName: example_value
                    givenName: example_value
                    surname: example_value
                    mail: example_value
                    userPrincipalName: example_value
                    jobTitle: example_value
                    department: example_value
                    officeLocation: example_value
                    companyName: example_value
                    businessPhones:
                    - example_value
                    mobilePhone: example_value
                    streetAddress: example_value
                    city: example_value
                    state: example_value
                    postalCode: example_value
                    country: example_value
                    preferredLanguage: example_value
                    accountEnabled: true
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastSignInDateTime: '2026-01-15T10:30:00Z'
                    usageLocation: example_value
                    passwordProfile:
                      forceChangePasswordNextSignIn: true
                      forceChangePasswordNextSignInWithMfa: true
                      password: example_value
                    identities:
                    - signInType: example_value
                      issuer: example_value
                      issuerAssignedId: '500123'
                    assignedLicenses:
                    - disabledPlans: {}
                      skuId: '500123'
                    manager:
                      '@odata.type': example_value
                      id: abc123
                      displayName: example_value
                    memberOf:
                    - '@odata.type': example_value
                      id: abc123
                      displayName: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateUser
      summary: Microsoft Office 365 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 without administrator roles. Requires User.ReadWrite, User.ReadWrite.All, or Directory.ReadWrite.All permission.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
            examples:
              UpdateuserRequestExample:
                summary: Default updateUser request
                x-microcks-default: true
                value:
                  displayName: example_value
                  givenName: example_value
                  surname: example_value
                  jobTitle: example_value
                  department: example_value
                  officeLocation: example_value
                  mobilePhone: example_value
                  businessPhones:
                  - example_value
                  streetAddress: example_value
                  city: example_value
                  state: example_value
                  postalCode: example_value
                  country: example_value
                  preferredLanguage: example_value
                  accountEnabled: true
                  usageLocation: example_value
                  passwordProfile:
                    forceChangePasswordNextSignIn: true
                    forceChangePasswordNextSignInWithMfa: true
                    password: example_value
      responses:
        '204':
          description: User updated successfully. No content returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteUser
      summary: Microsoft Office 365 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 30 days, they are permanently deleted. Requires User.ReadWrite.All or Directory.ReadWrite.All permission.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '204':
          description: User deleted successfully. No content returned.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me:
    get:
      operationId: getSignedInUser
      summary: Microsoft Office 365 Get Signed-in User
      description: Retrieve the properties and relationships of the currently signed-in user. The /me endpoint resolves to the signed-in user based on the access token. Requires User.Read permission at minimum.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The signed-in user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Getsignedinuser200Example:
                  summary: Default getSignedInUser 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    displayName: example_value
                    givenName: example_value
                    surname: example_value
                    mail: example_value
                    userPrincipalName: example_value
                    jobTitle: example_value
                    department: example_value
                    officeLocation: example_value
                    companyName: example_value
                    businessPhones:
                    - example_value
                    mobilePhone: example_value
                    streetAddress: example_value
                    city: example_value
                    state: example_value
                    postalCode: example_value
                    country: example_value
                    preferredLanguage: example_value
                    accountEnabled: true
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastSignInDateTime: '2026-01-15T10:30:00Z'
                    usageLocation: example_value
                    passwordProfile:
                      forceChangePasswordNextSignIn: true
                      forceChangePasswordNextSignInWithMfa: true
                      password: example_value
                    identities:
                    - signInType: example_value
                      issuer: example_value
                      issuerAssignedId: '500123'
                    assignedLicenses:
                    - disabledPlans: {}
                      skuId: '500123'
                    manager:
                      '@odata.type': example_value
                      id: abc123
                      displayName: example_value
                    memberOf:
                    - '@odata.type': example_value
                      id: abc123
                      displayName: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ODataError:
      type: object
      description: The error response from the Microsoft Graph API following OData conventions.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The error code string.
            message:
              type: string
              description: A human-readable error message.
            innerError:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                request-id:
                  type: string
                client-request-id:
                  type: string
          example: example_value
    AssignedLicense:
      type: object
      description: Represents a license assigned to a user.
      properties:
        disabledPlans:
          type: array
          items:
            type: string
          description: A collection of unique identifiers for disabled plans.
          example: []
        skuId:
          type: string
          description: The unique identifier for the SKU.
          example: '500123'
    UserUpdateRequest:
      type: object
      properties:
        displayName:
          type: string
          example: example_value
        givenName:
          type: string
          example: example_value
        surname:
          type: string
          example: example_value
        jobTitle:
          type: string
          example: example_value
        department:
          type: string
          example: example_value
        officeLocation:
          type: string
          example: example_value
        mobilePhone:
          type: string
          example: example_value
        businessPhones:
          type: array
          items:
            type: string
          example: []
        streetAddress:
          type: string
          example: example_value
        city:
          type: string
          example: example_value
        state:
          type: string
          example: example_value
        postalCode:
          type: string
          example: example_value
        country:
          type: string
          example: example_value
        preferredLanguage:
          type: string
          example: example_value
        accountEnabled:
          type: boolean
          example: true
        usageLocation:
          type: string
          example: example_value
        passwordProfile:
          $ref: '#/components/schemas/PasswordProfile'
    UserCollectionResponse:
      type: object
      properties:
        '@odata.context':
          type: string
          description: The OData context URL for the collection.
          example: example_value
        '@odata.count':
          type: integer
          description: The total count of items in the collection (if requested).
          example: 10
        '@odata.nextLink':
          type: string
          format: uri
          description: The URL to retrieve the next page of results.
          example: https://www.example.com
        value:
          type: array
          items:
            $ref: '#/components/schemas/User'
          example: []
    PasswordProfile:
      type: object
      description: Contains the password profile associated with a user.
      properties:
        forceChangePasswordNextSignIn:
          type: boolean
          description: Whether the user must change the password on the next sign-in.
          default: true
          example: true
        forceChangePasswordNextSignInWithMfa:
          type: boolean
          description: Whether the user must perform multi-factor authentication before being forced to change their password.
          default: false
          example: true
        password:
          type: string
          format: password
          description: The password for the user. Must satisfy the tenant's password complexity requirements. Minimum of 8 characters.
          example: example_value
    DirectoryObject:
      type: object
      description: Represents an Azure Active Directory object. The directoryObject type is the base type for many other directory entity types.
      properties:
        '@odata.type':
          type: string
          description: The OData type of the directory object.
          example: example_value
        id:
          type: string
          description: The unique identifier for the directory object.
          example: abc123
        displayName:
          type: string
          description: The name displayed for the directory object.
          example: example_value
    ObjectIdentity:
      type: object
      description: Represents an identity used to sign in to a user account.
      properties:
        signInType:
          type: string
          description: Specifies the type of user sign-in (e.g. emailAddress, userName, userPrincipalName).
          example: example_value
        issuer:
          type: string
          description: Specifies the issuer of the identity, for example contoso.onmicrosoft.com.
          example: example_value
        issuerAssignedId:
          type: string
          description: Specifies the unique value associated with the issuer- signInType combination.
          example: '500123'
    User:
      type: object
      description: Represents an Azure Active Directory user account. Inherits from directoryObject. Contains the user's profile information, organizational hierarchy, assigned licenses, and managed resources.
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier for the user. Inherited from directoryObject. GUID format.
          example: abc123
        displayName:
          type: string
          description: The name displayed in the address book for the user.
          example: example_value
        givenName:
          type: string
          description: The given name (first name) of the user.
          example: example_value
        surname:
          type: string
          description: The user's surname (family name or last name).
          example: example_value
        mail:
          type: string
          format: email
          description: The SMTP address for the user. This property cannot contain accent characters.
          example: example_value
        userPrincipalName:
          type: string
          description: The user principal name (UPN) of the user. The UPN is an Internet-style login name based on RFC 822. By convention, this should map to the user's email name.
          example: example_value
        jobTitle:
          type: string
          description: The user's job title.
          example: example_value
        department:
          type: string
          description: The name of the department in which the user works.
          example: example_value
        officeLocation:
          type: string
          description: The office location in the user's place of business.
          example: example_value
        companyName:
          type: string
          description: The company name associated with the user.
          example: example_value
        businessPhones:
          type: array
          items:
            type: string
          description: The telephone numbers for the user.
          example: []
        mobilePhone:
          type: string
          description: The primary cellular telephone number for the user.
          example: example_value
        streetAddress:
          type: string
          description: The street address of the user's place of business.
          example: example_value
        city:
          type: string
          description: The city in which the user is located.
          example: example_value
        state:
          type: string
          description: The state or province in the user's address.
          example: example_value
        postalCode:
          type: string
          description: The postal code for the user's postal address.
          example: example_value
        country:
          type: string
          description: The country or region in which the user is located; for example, US or UK.
          example: example_value
        preferredLanguage:
          type: string
          description: The preferred language for the user. Should follow ISO 639-1 Code; for example en-US.
          example: example_value
        accountEnabled:
          type: boolean
          description: True if the account is enabled; otherwise, false. Required when creating a user.
          example: true
        createdDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the user was created in ISO 8601 format.
          example: '2026-01-15T10:30:00Z'
        lastSignInDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time of the user's most recent interactive or non-interactive sign-in.
          example: '2026-01-15T10:30:00Z'
        usageLocation:
          type: string
          description: A two-letter country code (ISO 3166) required for users who will be assigned licenses. Not nullable.
          example: example_value
        passwordProfile:
          $ref: '#/components/schemas/PasswordProfile'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/ObjectIdentity'
          description: Represents the identities that can be used to sign in to this user account.
          example: []
        assignedLicenses:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/AssignedLicense'
          description: The licenses assigned to the user.
          example: []
        manager:
          $ref: '#/components/schemas/DirectoryObject'
        memberOf:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/DirectoryObject'
          description: The groups, directory roles, and administrative units the user is a member of.
          example: []
    UserCreateRequest:
      type: object
      required:
      - accountEnabled
      - displayName
      - mailNickname
      - userPrincipalName
      - passwordProfile
      properties:
        accountEnabled:
          type: boolean
          description: True if the account is enabled; otherwise, false.
          example: true
        displayName:
          type: string
          description: The name to display in the address book for the user.
          example: example_value
        mailNickname:
          type: string
          description: The mail alias for the user.
          example: example_value
        userPrincipalName:
          type: string
          description: The user principal name (someuser@contoso.com).
          example: example_value
        passwordProfile:
          $ref: '#/components/schemas/PasswordProfile'
        givenName:
          type: string
          example: example_value
        surname:
          type: string
          example: example_value
        jobTitle:
          type: string
          example: example_value
        department:
          type: string
          example: example_value
        officeLocation:
          type: string
          example: example_value
        mobilePhone:
          type: string
          example: example_value
        usageLocation:
          type: string
          example: example_value
  responses:
    BadRequest:
      description: Bad request. The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    InternalServerError:
      description: Internal server error. An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    TooManyRequests:
      description: Too many requests. The application has been throttled.
      headers:
        Retry-After:
          description: The number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Forbidden:
      description: Forbidden. Insufficient permissions to complete the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized. A valid access token is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  parameters:
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response.
      schema:
        type: string
    top:
      name: $top
      in: query
      description: The number of items to return in a result set. Maximum value depends on the API.
      schema:
        type: integer
        minimum: 1
    search:
      name: $search
      in: query
      description: Search expression to filter results. Uses KQL syntax for directory objects.
      schema:
        type: string
    userId:
      name: user-id
      in: path
      required: true
      description: The unique identifier of the user (GUID) or the userPrincipalName.
      schema:
        type: string
    skip:
      name: $skip
      in: query
      description: The number of items to skip in the result set.
      schema:
        type: integer
        minimum: 0
    count:
      name: $count
      in: query
      description: Include a count of the total number of items in a collection alongside the page of data values.
      schema:
        type: boolean
    expand:
      name: $expand
      in: query
      description: Comma-separated list of relationships to expand and include in the response.
      schema:
        type: string
    filter:
      name: $filter
      in: query
      description: OData filter expression to restrict the set of items returned.
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties for sorting results.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: Microsoft identity platform OAuth 2.0 authorization. Supports delegated (user) and application-only permissions. Microsoft Graph uses scopes to control access to resources.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
     

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-office-365/refs/heads/main/openapi/microsoft-office-365-users-api-openapi.yml