apple_device-management/declarative/status/app.managed.list.yaml

title: Status App Managed List
description: The client's declarative managed apps.
payload:
  statusitemtype: app.managed.list
  supportedOS:
    iOS:
      introduced: '17.2'
      allowed-enrollments:
      - supervised
      - device
      - user
      allowed-scopes:
      - system
      sharedipad:
        allowed-scopes:
        - system
    macOS:
      introduced: n/a
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  beta: true
payloadkeys:
- key: app.managed.list
  title: Status item value.
  type: <array>
  presence: required
  content: An array of dictionaries that describe the device's declarative managed
    apps.
  subkeytype: App
  subkeys:
  - key: status_value
    type: <dictionary>
    subkeys:
    - key: identifier
      title: Unique identifier of the app.
      type: <string>
      presence: required
      content: The app's bundle id, which is unique.
    - key: _removed
      title: Indicates removal of the app.
      type: <boolean>
      presence: optional
      default: false
      content: To indicate removal of an app, this key's value is set to true, and
        only this key and the "identifier" key will be present in the status item
        object.
    - key: declaration-identifier
      title: Identifier of the declaration that controls the app.
      type: <string>
      presence: optional
      content: The identifier of the declaration that controls the app.
    - key: name
      title: App name
      type: <string>
      presence: optional
      content: The name of the app.
    - key: external-version-id
      title: External version id
      type: <integer>
      presence: optional
      content: |-
        The app's external version ID. You can also retrieve this value from the store through the contentMetadataLookupUrl <https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/MobileDeviceManagementProtocolRef/5-Web_Service_Protocol_VPP/webservice.html#//apple_ref/doc/uid/TP40017387-CH8-SW209> of VPPServiceConfigSrv <https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/MobileDeviceManagementProtocolRef/5-Web_Service_Protocol_VPP/webservice.html#//apple_ref/doc/uid/TP40017387-CH8-SW15>.
        In the response from 'uclient-api.itunes.apple.com' URL, there's an 'externalId' at the path 'results.<adamId>.offers[0].version.externalId'. If the current external version identifier of an app on the store doesn't match the external version identifier reported by the device, there may be an app update available for the device.
    - key: version
      title: Version
      type: <string>
      presence: optional
      content: The version of the app.
    - key: short-version
      title: Short version
      type: <string>
      presence: optional
      content: The short version of the app.
    - key: state
      title: Managed application list status
      type: <string>
      presence: optional
      rangelist:
      - optional
      - queued
      - prompting-for-consent
      - prompting-for-login
      - prompting-for-management
      - downloading
      - installing
      - managed
      - managed-but-uninstalled
      - failed
      content: |-
        The status of the app, which has the following possible values:

        * 'optional': The app is optional and the user has to trigger its installation.
        * 'queued': Installation of the app started.
        * 'prompting-for-consent': The system is displaying a prompt to the user to proceed with app installation.
        * 'prompting-for-login': The system is displaying an App Store sign-in prompt to the user to allow app installation.
        * 'prompting-for-management': The system is displaying a prompt to the user to allow changing the installed app to a managed app.
        * 'downloading': The system is downloading an app update.
        * 'installing': The system is installing an app update.
        * 'managed': The app is installed and managed.
        * 'managed-but-uninstalled': The app is managed, but the user removed it. The app remains managed if the system installs it again.
        * 'failed': An app update failed.
    - key: update-state
      title: Managed application update status
      type: <string>
      presence: optional
      rangelist:
      - available
      - prompting-for-update
      - prompting-for-update-login
      - updating
      - failed
      content: |-
        The update status of the app, which has the following possible values:

        * 'available': An update is available for the app.
        * 'prompting-for-update': The system is displaying a prompt to the user to proceed with app installation.
        * 'prompting-for-update-login': The system is displaying an App Store sign-in prompt to the user to allow app installation.
        * 'updating': The app is updating.
        * 'failed': The app update failed.

        This key is only present if 'state' is 'managed' and an update is available.
    - key: reasons
      title: Status Reasons
      type: <array>
      presence: optional
      content: An array that contains additional details about the app state, including
        errors.
      subkeytype: StatusReason
      subkeys:
      - key: _reasons
        title: Status Reason
        type: <dictionary>
        content: Information about a status error.
        subkeytype: StatusReason
        subkeys:
        - key: code
          title: Error Code
          type: <string>
          presence: required
          content: A code for the state.
        - key: description
          title: Error Description
          type: <string>
          presence: optional
          content: A description of the state.
        - key: details
          title: Error Details
          type: <dictionary>
          presence: optional
          content: A dictionary that contains additional details about the state.
          subkeys:
          - key: ANY
            type: <any>
            presence: optional
            content: Additional keys may be present.
reasons:
- value: Error.UnmanagedAppAlreadyInstalled
  description: An unmanaged app is already installed and cannot be managed.
- value: Error.DuplicateConfiguredApp
  description: The app is already being managed.
- value: Error.UserRejected
  description: The user rejected management of the app.
- value: Error.AppStoreDisabled
  description: The App Store is disabled.
- value: Error.LicenseNotFound
  description: A license for the app was not available.
- value: Error.InvalidAppID
  description: The app id could not be found.
- value: Error.NotAnApp
  description: The downloaded data is not a valid app.
- value: Error.NotSupported
  description: The app is not supported on this device.
- value: Error.DownloadFailed
  description: The app download failed.
  details:
  - key: Timestamp
    type: <string>
    description: The RFC 3339 timestamp of the last download failure.
- value: Error.InstallFailed
  description: The app install failed.
  details:
  - key: Timestamp
    type: <string>
    description: The RFC 3339 timestamp of the last install failure.
- value: Info.UpdateAvailable
  description: An update is available for the app.
- value: Error.UpdateFailed
  description: The app update failed.
  details:
  - key: Timestamp
    type: <string>
    description: The RFC 3339 timestamp of the last update failure.