apple_device-management/mdm/commands/application.install.yaml

title: Install Application Command
description: Install a third-party app on a device.
payload:
  requesttype: InstallApplication
  supportedOS:
    iOS:
      introduced: '5.0'
      accessrights: AllowAppInstallation
      supervised: false
      requiresdep: false
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: allowed
    macOS:
      introduced: '10.9'
      accessrights: AllowAppInstallation
      devicechannel: true
      userchannel: true
      supervised: false
      requiresdep: false
      userenrollment:
        mode: allowed
    tvOS:
      introduced: '10.2'
      accessrights: AllowAppInstallation
      supervised: false
    visionOS:
      introduced: '1.1'
      accessrights: AllowAppInstallation
      supervised: false
      requiresdep: false
      userenrollment:
        mode: allowed
    watchOS:
      introduced: '10.0'
      accessrights: AllowAppInstallation
      supervised: false
payloadkeys:
- key: iTunesStoreID
  type: <integer>
  presence: optional
  content: The app's iTunes Store identifier.
- key: Identifier
  supportedOS:
    iOS:
      introduced: '7.0'
  type: <string>
  presence: optional
  content: |-
    The app's bundle identifier.

    > Important:
    > For a watchOS app, the identifier needs to be the watch's bundle identifier, which differs from the main bundle identifier for the iPhone the watch pairs with. Obtain the watch's bundle identifier for an app with a watch bundle, in the `watchBundleId` key that's part of the Content Metadata query. For more information on this query, see `Getting app and book information (Legacy)`.
- key: Options
  supportedOS:
    iOS:
      introduced: '7.0'
  type: <dictionary>
  presence: optional
  content: A dictionary that contains the app installation options.
  subkeys:
  - key: PurchaseMethod
    type: <integer>
    presence: optional
    rangelist:
    - 0
    - 1
    default: 0
    content: |-
      The app's purchase type, which must be one of the following values:

      - `0`: Free apps and Legacy Volume Purchase Program (VPP) with a redemption code. This option is only available in iOS.
      - `1`: Volume Purchase Program (VPP) app assignment.

      Set this value to `1` to install first-party apps without user login to the iTunes Store, such as Mail or Safari, or to install an iOS app with user enrollment.
- key: ManifestURL
  supportedOS:
    iOS:
      introduced: '7.0'
  type: <string>
  presence: optional
  content: The URL of the app manifest, which needs to begin with `https:`. The server
    returns the manifest as a property list that uses the `ManifestURL` format.
- key: ManagementFlags
  supportedOS:
    macOS:
      introduced: '11.0'
      userenrollment:
        mode: forbidden
  type: <integer>
  presence: optional
  rangelist:
  - 1
  - 4
  - 5
  content: |-
    A bitwise OR of the management flags. The possible values are:

    - `1`: If `InstallAsManaged` is `true`, remove the app upon removal of the MDM profile.
    - `4`: Prevent backup of app data.
    - `5`: Both `1` and `4`.
- key: Configuration
  supportedOS:
    iOS:
      introduced: '7.0'
    macOS:
      introduced: '11.0'
  type: <dictionary>
  presence: optional
  content: A dictionary that contains the initial configuration of the app, if you
    choose to provide it.
  subkeys:
  - key: ANY
    type: <any>
    presence: optional
    content: An app configuration key.
- key: Attributes
  supportedOS:
    iOS:
      introduced: '7.0'
    macOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: A dictionary that contains the initial attributes of the app, if you choose
    to provide it.
  subkeys:
  - key: VPNUUID
    supportedOS:
      tvOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: A per-app VPN unique identifier for this app.
  - key: ContentFilterUUID
    supportedOS:
      iOS:
        introduced: '16.0'
      tvOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The content filter UUID for this app.
  - key: DNSProxyUUID
    supportedOS:
      iOS:
        introduced: '16.0'
      tvOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The DNS proxy UUID for this app.
  - key: RelayUUID
    supportedOS:
      iOS:
        introduced: '17.0'
      tvOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The relay UUID for this app.
  - key: AssociatedDomains
    supportedOS:
      iOS:
        introduced: '13.0'
      tvOS:
        introduced: n/a
    type: <array>
    presence: optional
    content: An array that contains the associated domains to add to this app.
    subkeys:
    - key: AssociatedDomain
      type: <string>
  - key: AssociatedDomainsEnableDirectDownloads
    supportedOS:
      iOS:
        introduced: '14.0'
      tvOS:
        introduced: n/a
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, perform claimed site association verification directly at
      the domain instead of on Apple's servers. Only set this to `true` for domains
      that can't access the internet.
  - key: Removable
    supportedOS:
      iOS:
        introduced: '14.0'
      tvOS:
        introduced: '14.0'
    type: <boolean>
    presence: optional
    default: true
    content: If `false`, this app isn't removable while it's a managed app.
  - key: TapToPayScreenLock
    supportedOS:
      iOS:
        introduced: '16.4'
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, Tap to Pay on iPhone requires users to use Face ID or a passcode
      to unlock their device after every transaction that requires a customer's card
      PIN. If `false`, the user can configure this setting on their device.
  - key: CellularSliceUUID
    supportedOS:
      iOS:
        introduced: '17.0'
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The data network name (DNN) or app category. For DNN, the value is `DNN:name`,
      where `name` is the carrier-provided DNN name. For app category, the value is
      `AppCategory:category`, where `category` is a carrier-provided string like "Enterprise1".
  - key: Hideable
    supportedOS:
      iOS:
        introduced: '18.1'
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <boolean>
    presence: optional
    default: true
    content: If `false`, the system prevents the user from hiding the app. It doesn't
      affect the user's ability to leave it in the App Library, while removing it
      from the Home Screen.
  - key: Lockable
    supportedOS:
      iOS:
        introduced: '18.1'
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
      watchOS:
        introduced: n/a
    type: <boolean>
    presence: optional
    default: true
    content: If `false`, the system prevents the user from locking the app. This also
      prevents the user from hiding the app.
- key: ChangeManagementState
  supportedOS:
    iOS:
      introduced: '9.0'
      userenrollment:
        mode: forbidden
    macOS:
      introduced: '11.0'
      userenrollment:
        mode: forbidden
    visionOS:
      userenrollment:
        mode: forbidden
  type: <string>
  presence: optional
  rangelist:
  - Managed
  content: |-
    The change management state. This value doesn't work with the user enrollment feature introduced in iOS 13, or any type of account driven enrollment. The only possible value is:

    * `Managed`: Take management of the app if the user installed it already and `InstallAsManaged` is `true`.
- key: InstallAsManaged
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '11.0'
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: |-
    If `true`, install the app as a managed app. Otherwise, the system installs the app as unmanaged. If you reinstall a manged app and omit this value or set it to `false`, the app becomes unmanaged.

    For manifest-based installs, if `true`, the system only considers apps installed in `/Applications` as managed. In macOS 11 through 13, the system requires that the `pkg` only contains a single signed app.
- key: iOSApp
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '11.0'
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the app is an iOS app that can run on a Mac with Apple silicon
    in macOS 11 and later.
responsekeys:
- key: Identifier
  type: <string>
  presence: optional
  content: |-
    The app's bundle identifier, if the user accepted the request.

    > Note:
    > For a watchOS app, the identifier is the watch's bundle identifier, which differs from the main bundle identifier for the iPhone the watch pairs with.
- key: State
  type: <string>
  presence: optional
  rangelist:
  - Queued
  - NeedsRedemption
  - Redeeming
  - Prompting
  - PromptingForLogin
  - ValidatingPurchase
  - Installing
  - Managed
  - ManagedButUninstalled
  - UserInstalledApp
  - UserRejected
  - PromptingForUpdate
  - PromptingForUpdateLogin
  - ValidatingUpdate
  - Updating
  - UpdateRejected
  - PromptingForManagement
  - ManagementRejected
  - Failed
  - Unknown
  content: The app's installation state, if the user accepted the request. If this
    value is `NeedsRedemption`, the server needs to send a redemption code to complete
    the app installation.
- key: RejectionReason
  type: <string>
  presence: optional
  rangelist:
  - AppAlreadyInstalled
  - AppAlreadyQueued
  - AppStoreDisabled
  - CouldNotVerifyAppID
  - ManagementChangeNotSupported
  - NotAnApp
  - NotSupported
  - Other
  - PurchaseMethodNotSupported
  - PurchaseMethodNotSupportedInMultiUser
  content: The reason, if installation fails. macOS always returns "Other".
notes:
- title: ''
  content: |-
    The request must contain only one of these keys: `iTunesStoreID`, `Identifier`, or `ManifestURL`.

    Installation prompts the user to approve or cancel the update. If the device is supervised, the device only prompts when the app to install is in the foreground.

    Set the organization name that appears in this prompt in the `OrganizationInfo` dictionary using the `Settings` command.

    If the app is a managed app, this command updates it. This command fails if Declarative Device Management is managing the app.

    In macOS, the device returns an `Acknowledged` response after validating the parameters, but before downloading and installing the app. However, it doesn't notify the MDM server about errors that occur during the installation process.

    For macOS VPP app installations, if the app is device licensed, the system must receive the `InstallApplication` command on the device channel. If the app is user licensed, the system must receive the `InstallApplication` command on the user channel.

    Prior to iOS 16.0 and tvOS 16.0, this command would return `NotNow` when Setup Assistant was running. Starting in iOS 16.0 and tvOS 16.0, the command may be sent to supervised devices during Setup Assistant. However, you should only attempt to install device-based VPP apps or enterprise apps while in the awaiting configuration state, as it is unlikely the device would have an App Store account configured, and thus commands that depend on one will fail.

    Refer to the following sections to determine supported channels and requirements, and to see an example request and response.
examples:
- title: Example request and response
  files:
  - tab: Enterprise
    description: This command installs an enterprise app.
    request-file: examples/mdm/commands/application.install/example1.plist
    response-file: examples/mdm/commands/application.install/example2.plist
  - tab: App Store
    description: This command installs an App Store app.
    request-file: examples/mdm/commands/application.install/example3.plist
    response-file: examples/mdm/commands/application.install/example4.plist