Microsoft Intune Managed Devices API

openapi: 3.1.0
info:
  title: Microsoft Intune Graph Device Compliance Policies Managed Devices API
  description: The Microsoft Graph API for Intune enables programmatic access to Intune information and actions for your tenant. The API performs the same Intune operations as those available through the Microsoft Intune admin center, including managed device management, device configuration, and compliance policy enforcement. Requires an active Intune license for the tenant.
  version: 1.0.0
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  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 production endpoint
security:
- oauth2:
  - DeviceManagementManagedDevices.Read.All
  - DeviceManagementConfiguration.Read.All
tags:
- name: Managed Devices
  description: Operations for managing devices enrolled in Intune. Includes listing, retrieving, creating, updating, and deleting managed device records.
  externalDocs:
    url: https://learn.microsoft.com/en-us/graph/api/resources/intune-devices-manageddevice?view=graph-rest-1.0
paths:
  /deviceManagement/managedDevices:
    get:
      operationId: listManagedDevices
      summary: Microsoft Intune List managed devices
      description: List properties and relationships of the managedDevice objects. Returns all devices managed or pre-enrolled through Intune for the tenant.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A collection of managedDevice objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  '@odata.count':
                    type: integer
                  '@odata.nextLink':
                    type: string
                    format: uri
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/managedDevice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.Read.All
        - DeviceManagementManagedDevices.ReadWrite.All
    post:
      operationId: createManagedDevice
      summary: Microsoft Intune Create managed device
      description: Create a new managedDevice object.
      tags:
      - Managed Devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/managedDevice'
      responses:
        '201':
          description: The created managedDevice object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/managedDevice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}:
    get:
      operationId: getManagedDevice
      summary: Microsoft Intune Get managed device
      description: Read properties and relationships of a managedDevice object. Returns details for a single device managed through Intune.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested managedDevice object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/managedDevice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.Read.All
        - DeviceManagementManagedDevices.ReadWrite.All
    patch:
      operationId: updateManagedDevice
      summary: Microsoft Intune Update managed device
      description: Update the properties of a managedDevice object.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/managedDevice'
      responses:
        '200':
          description: The updated managedDevice object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/managedDevice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
    delete:
      operationId: deleteManagedDevice
      summary: Microsoft Intune Delete managed device
      description: Deletes a managedDevice.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The managedDevice was successfully deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/retire:
    post:
      operationId: retireManagedDevice
      summary: Microsoft Intune Retire a device
      description: Retire a device. Removes company data from the device while keeping personal data intact. The device is removed from Intune management.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The retire action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/wipe:
    post:
      operationId: wipeManagedDevice
      summary: Microsoft Intune Wipe a device
      description: Wipe a device. Factory resets the device, removing all data including both company and personal data.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                keepEnrollmentData:
                  type: boolean
                  description: Whether to keep enrollment data during the wipe.
                keepUserData:
                  type: boolean
                  description: Whether to keep user data during the wipe.
                macOsUnlockCode:
                  type: string
                  description: The macOS unlock code for the wipe.
      responses:
        '204':
          description: No content. The wipe action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/syncDevice:
    post:
      operationId: syncManagedDevice
      summary: Microsoft Intune Sync a device
      description: Trigger a sync for a managed device to check in with Intune.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The sync action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/remoteLock:
    post:
      operationId: remoteLockManagedDevice
      summary: Microsoft Intune Remote lock a device
      description: Remotely lock a managed device.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The remote lock action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/resetPasscode:
    post:
      operationId: resetPasscodeManagedDevice
      summary: Microsoft Intune Reset device passcode
      description: Reset the passcode on a managed device.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The reset passcode action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
  /deviceManagement/managedDevices/{managedDeviceId}/rebootNow:
    post:
      operationId: rebootManagedDevice
      summary: Microsoft Intune Reboot a device
      description: Remotely reboot a managed device.
      tags:
      - Managed Devices
      parameters:
      - $ref: '#/components/parameters/managedDeviceId'
      responses:
        '204':
          description: No content. The reboot action was successfully initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/ODataError'
      security:
      - oauth2:
        - DeviceManagementManagedDevices.ReadWrite.All
components:
  responses:
    Forbidden:
      description: Forbidden. The caller does not have the required permissions.
      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'
    Unauthorized:
      description: Unauthorized. The request requires valid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/odataError'
    ODataError:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/odataError'
  schemas:
    configurationManagerClientEnabledFeatures:
      type: object
      description: Configuration Manager client enabled features.
      properties:
        '@odata.type':
          type: string
          default: microsoft.graph.configurationManagerClientEnabledFeatures
        inventory:
          type: boolean
          description: Whether inventory is managed by Intune.
        modernApps:
          type: boolean
          description: Whether modern application is managed by Intune.
        resourceAccess:
          type: boolean
          description: Whether resource access is managed by Intune.
        deviceConfiguration:
          type: boolean
          description: Whether device configuration is managed by Intune.
        compliancePolicy:
          type: boolean
          description: Whether compliance policy is managed by Intune.
        windowsUpdateForBusiness:
          type: boolean
          description: Whether Windows Update for Business is managed by Intune.
    odataError:
      type: object
      description: OData error response.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
            message:
              type: string
              description: Error message.
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                  description: Request ID for tracing.
                date:
                  type: string
                  format: date-time
                  description: Date and time of the error.
    managedDevice:
      type: object
      description: Devices that are managed or pre-enrolled through Intune. Represents a physical or virtual device managed by the Intune service.
      properties:
        '@odata.type':
          type: string
          default: '#microsoft.graph.managedDevice'
        id:
          type: string
          description: Unique identifier for the device. Read-only.
          readOnly: true
        userId:
          type: string
          description: Unique identifier for the user associated with the device. Read-only.
          readOnly: true
        deviceName:
          type: string
          description: Name of the device. Read-only.
          readOnly: true
        managedDeviceOwnerType:
          type: string
          description: Ownership of the device. Can be company or personal.
          enum:
          - unknown
          - company
          - personal
        enrolledDateTime:
          type: string
          format: date-time
          description: Enrollment time of the device. Read-only.
          readOnly: true
        lastSyncDateTime:
          type: string
          format: date-time
          description: The date and time that the device last completed a successful sync with Intune. Read-only.
          readOnly: true
        operatingSystem:
          type: string
          description: Operating system of the device (Windows, iOS, etc.). Read-only.
          readOnly: true
        complianceState:
          type: string
          description: Compliance state of the device.
          enum:
          - unknown
          - compliant
          - noncompliant
          - conflict
          - error
          - inGracePeriod
          - configManager
        jailBroken:
          type: string
          description: Whether the device is jail broken or rooted. Read-only.
          readOnly: true
        managementAgent:
          type: string
          description: Management channel of the device (Intune, EAS, etc.).
          enum:
          - eas
          - mdm
          - easMdm
          - intuneClient
          - easIntuneClient
          - configurationManagerClient
          - configurationManagerClientMdm
          - configurationManagerClientMdmEas
          - unknown
          - jamf
          - googleCloudDevicePolicyController
        osVersion:
          type: string
          description: Operating system version of the device. Read-only.
          readOnly: true
        easActivated:
          type: boolean
          description: Whether the device is Exchange ActiveSync activated. Read-only.
          readOnly: true
        easDeviceId:
          type: string
          description: Exchange ActiveSync Id of the device. Read-only.
          readOnly: true
        easActivationDateTime:
          type: string
          format: date-time
          description: Exchange ActivationSync activation time of the device. Read-only.
          readOnly: true
        azureADRegistered:
          type: boolean
          description: Whether the device is Azure Active Directory registered. Read-only.
          readOnly: true
        deviceEnrollmentType:
          type: string
          description: Enrollment type of the device. Read-only.
          readOnly: true
          enum:
          - unknown
          - userEnrollment
          - deviceEnrollmentManager
          - appleBulkWithUser
          - appleBulkWithoutUser
          - windowsAzureADJoin
          - windowsBulkUserless
          - windowsAutoEnrollment
          - windowsBulkAzureDomainJoin
          - windowsCoManagement
          - windowsAzureADJoinUsingDeviceAuth
          - appleUserEnrollment
          - appleUserEnrollmentWithServiceAccount
        activationLockBypassCode:
          type: string
          description: The code that allows the Activation Lock on managed device to be bypassed. Read-only.
          readOnly: true
        emailAddress:
          type: string
          description: Email(s) for the user associated with the device. Read-only.
          readOnly: true
        azureADDeviceId:
          type: string
          description: The unique identifier for the Azure Active Directory device. Read-only.
          readOnly: true
        deviceRegistrationState:
          type: string
          description: Device registration state. Read-only.
          readOnly: true
          enum:
          - notRegistered
          - registered
          - revoked
          - keyConflict
          - approvalPending
          - certificateReset
          - notRegisteredPendingEnrollment
          - unknown
        deviceCategoryDisplayName:
          type: string
          description: Device category display name. Read-only.
          readOnly: true
        isSupervised:
          type: boolean
          description: Device supervised status. Read-only.
          readOnly: true
        exchangeLastSuccessfulSyncDateTime:
          type: string
          format: date-time
          description: Last time the device contacted Exchange. Read-only.
          readOnly: true
        exchangeAccessState:
          type: string
          description: The Access State of the device in Exchange. Read-only.
          readOnly: true
          enum:
          - none
          - unknown
          - allowed
          - blocked
          - quarantined
        exchangeAccessStateReason:
          type: string
          description: The reason for the device's access state in Exchange. Read-only.
          readOnly: true
          enum:
          - none
          - unknown
          - exchangeGlobalRule
          - exchangeIndividualRule
          - exchangeDeviceRule
          - exchangeUpgrade
          - exchangeMailboxPolicy
          - other
          - compliant
          - notCompliant
          - notEnrolled
          - unknownLocation
          - mfaRequired
          - azureADBlockDueToAccessPolicy
          - compromisedPassword
          - deviceNotKnownWithManagedApp
        remoteAssistanceSessionUrl:
          type: string
          format: uri
          description: URL that allows a Remote Assistance session to be established with the device. Read-only.
          readOnly: true
        remoteAssistanceSessionErrorDetails:
          type: string
          description: An error string that identifies issues when creating Remote Assistance session objects. Read-only.
          readOnly: true
        isEncrypted:
          type: boolean
          description: Device encryption status. Read-only.
          readOnly: true
        userPrincipalName:
          type: string
          description: Device user principal name. Read-only.
          readOnly: true
        model:
          type: string
          description: Model of the device. Read-only.
          readOnly: true
        manufacturer:
          type: string
          description: Manufacturer of the device. Read-only.
          readOnly: true
        imei:
          type: string
          description: IMEI. Read-only.
          readOnly: true
        complianceGracePeriodExpirationDateTime:
          type: string
          format: date-time
          description: The DateTime when device compliance grace period expires. Read-only.
          readOnly: true
        serialNumber:
          type: string
          description: Serial number. Read-only.
          readOnly: true
        phoneNumber:
          type: string
          description: Phone number of the device. Read-only.
          readOnly: true
        androidSecurityPatchLevel:
          type: string
          description: Android security patch level. Read-only.
          readOnly: true
        userDisplayName:
          type: string
          description: User display name. Read-only.
          readOnly: true
        configurationManagerClientEnabledFeatures:
          $ref: '#/components/schemas/configurationManagerClientEnabledFeatures'
        wiFiMacAddress:
          type: string
          description: Wi-Fi MAC address. Read-only.
          readOnly: true
        deviceHealthAttestationState:
          $ref: '#/components/schemas/deviceHealthAttestationState'
        subscriberCarrier:
          type: string
          description: Subscriber carrier. Read-only.
          readOnly: true
        meid:
          type: string
          description: MEID. Read-only.
          readOnly: true
        totalStorageSpaceInBytes:
          type: integer
          format: int64
          description: Total storage in bytes. Read-only.
          readOnly: true
        freeStorageSpaceInBytes:
          type: integer
          format: int64
          description: Free storage in bytes. Read-only.
          readOnly: true
        managedDeviceName:
          type: string
          description: Automatically generated name to identify a device. Can be overwritten to a user friendly name.
        partnerReportedThreatState:
          type: string
          description: Indicates the threat state of a device when a Mobile Threat Defense partner is in use. Read-only.
          readOnly: true
          enum:
          - unknown
          - activated
          - deactivated
          - secured
          - lowSeverity
          - mediumSeverity
          - highSeverity
          - unresponsive
          - compromised
          - misconfigured
        requireUserEnrollmentApproval:
          type: boolean
          description: Reports if the managed iOS device is user approval enrollment. Read-only.
          readOnly: true
        managementCertificateExpirationDate:
          type: string
          format: date-time
          description: Reports device management certificate expiration date. Read-only.
          readOnly: true
        iccid:
          type: string
          description: Integrated Circuit Card Identifier - a SIM card's unique identification number. Read-only.
          readOnly: true
        udid:
          type: string
          description: Unique Device Identifier for iOS and macOS devices. Read-only.
          readOnly: true
        notes:
          type: string
          description: Notes on the device created by IT Admin.
        ethernetMacAddress:
          type: string
          description: Ethernet MAC Address of the device. Read-only.
          readOnly: true
        physicalMemoryInBytes:
          type: integer
          format: int64
          description: Total memory in bytes. Read-only.
          readOnly: true
        enrollmentProfileName:
          type: string
          description: Name of the enrollment profile assigned to the device. Read-only.
          readOnly: true
    deviceHealthAttestationState:
      type: object
      description: Device health attestation state.
      properties:
        '@odata.type':
          type: string
          default: microsoft.graph.deviceHealthAttestationState
        lastUpdateDateTime:
          type: string
          description: The timestamp of the last update.
        contentNamespaceUrl:
          type: string
          format: uri
          description: The DHA report version (namespace version).
        deviceHealthAttestationStatus:
          type: string
          description: The DHA report version (namespace version).
        contentVersion:
          type: string
          description: The HealthAttestation state schema version.
        issuedDateTime:
          type: string
          format: date-time
          description: The DateTime when device was evaluated or issued to MDM.
        attestationIdentityKey:
          type: string
          description: The attestation identity key.
        resetCount:
          type: integer
          format: int64
          description: The number of times a PC device has hibernated or resumed.
        restartCount:
          type: integer
          format: int64
          description: The number of times a PC device has rebooted.
        bitLockerStatus:
          type: string
          description: On or Off of BitLocker Drive Encryption.
        bootManagerVersion:
          type: string
          description: The version of the Boot Manager.
        secureBoot:
          type: string
          description: When Secure Boot is enabled the core components must have correct cryptographic signatures.
        codeIntegrity:
          type: string
          description: When code integrity is enabled code that does not meet the policy is blocked from loading.
        testSigning:
          type: string
          description: When test signing is allowed the device does not enforce signature validation during boot.
        safeMode:
          type: string
          description: Safe mode is a troubleshooting option for Windows that starts the computer in a limited state.
        windowsPE:
          type: string
          description: Operating system running with limited services that is used to prepare a computer for Windows.
        tpmVersion:
          type: string
          description: The security version number of the Boot Application.
        virtualSecureMode:
          type: string
          description: VSM is a container that protects high value assets from a compromised kernel.
  parameters:
    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 for filtering results.
      schema:
        type: string
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response.
      schema:
        type: string
    skip:
      name: $skip
      in: query
      description: Number of items to skip in the result set.
      schema:
        type: integer
        minimum: 0
    count:
      name: $count
      in: query
      description: Include count of items in the result set.
      schema:
        type: boolean
    top:
      name: $top
      in: query
      description: Number of items to return in a result set.
      schema:
        type: integer
        minimum: 0
    managedDeviceId:
      name: managedDeviceId
      in: path
      required: true
      description: The unique identifier of the managed device.
      schema:
        type: string
    search:
      name: $search
      in: query
      description: Search string for filtering results.
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort the result set by.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using Azure Active Directory. Requires an active Intune license for the tenant.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            DeviceManagementManagedDevices.Read.All: Read Microsoft Intune managed devices
            DeviceManagementManagedDevices.ReadWrite.All: Read and write Microsoft Intune managed devices
            DeviceManagementConfiguration.Read.All: Read Microsoft Intune device configuration and policies
            DeviceManagementConfiguration.ReadWrite.All: Read and write Microsoft Intune device configuration and policies
externalDocs:
  description: Microsoft Graph Intune API Overview
  url: https://learn.microsoft.com/en-us/graph/api/resources/intune-graph-overview?view=graph-rest-1.0