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

title: Status App Managed List
description: The status item that lists the device'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: '26.0'
      allowed-enrollments:
      - supervised
      - user
      allowed-scopes:
      - system
      - user
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '2.4'
      allowed-enrollments:
      - supervised
      - device
      - user
      allowed-scopes:
      - system
    watchOS:
      introduced: n/a
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
    title: Status value
    type: <dictionary>
    content: A managed app.
    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: If `true`, the system removed the app and only this key and the `identifier`
        key are 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 identifier
      type: <integer>
      presence: optional
      content: |-
        The app's external version identifier. You can also retrieve this value from the App Store. For more information, see `Apps and books metadata for organizations`.

        If the current external version identifier of an app on the App 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
      - not-present
      - 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`: The system has started installation of the app.
        - `not-present`: Management of the app occurs after it's installed.
        - `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 the app.
        - `installing`: The system is installing the app.
        - `managed`: The app is installed and managed.
        - `managed-but-uninstalled`: The app is required, but the system hasn't installed it. The app becomes managed if the system installs it again. If the user removes an optional app, its state is `optional`, not `managed-but-uninstalled`.
        - `failed`: The app install 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.

        > Note:
        > This key is only present if `state` is `managed` and an update is available.
    - key: config-state
      title: Managed application configuration status
      supportedOS:
        iOS:
          introduced: '18.4'
        macOS:
          introduced: '27.0'
      type: <dictionary>
      presence: optional
      content: The status of app or extension managed configurations. This key is
        only present when managed configurations are available for the managed app
        or any of its extensions.
      subkeytype: ManagedConfiguration
      subkeys:
      - key: app-config-state
        title: Application managed configuration status
        type: <dictionary>
        presence: optional
        content: The status of any app managed configuration. This key is only present
          when the managed app has a managed configuration.
        subkeytype: ManagedConfigurationState
        subkeys: &id001
        - key: state
          title: Managed configuration status
          type: <string>
          presence: required
          rangelist:
          - unknown
          - invalid
          - valid
          content: |-
            The managed configuration status.
            - `unknown`: The device hasn't read the managed configuration.
            - `invalid`: The device read the managed configuration and found it to be invalid.
            - `valid`: The device read the managed configuration and found it to be valid.
      - key: extension-config-state
        title: Extensions managed configuration status
        type: <dictionary>
        presence: optional
        content: The status of any app extension managed configuration. This key's
          value is a dictionary whose keys are the bundle identifiers of app extensions
          that have a managed configuration. The values of each key represent the
          status of the corresponding app extension's managed configuration.
        subkeys:
        - key: ANY
          type: <dictionary>
          presence: optional
          content: The bundle identifier of the managed app extension.
          subkeytype: ManagedConfigurationState
          subkeys: *id001
    - 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.AppStoreDisabled
  description: The App Store is disabled.
- value: Error.DownloadFailed
  description: The app download failed.
  details:
  - key: Timestamp
    type: <string>
    valuetype: timestamp
    description: The RFC 3339 timestamp of the last download failure.
- value: Error.DuplicateConfiguredApp
  description: The app is already being managed.
- value: Error.InstallFailed
  description: The app install failed.
  details:
  - key: Timestamp
    type: <string>
    valuetype: timestamp
    description: The RFC 3339 timestamp of the last install failure.
- value: Error.InvalidAppID
  description: The app id could not be found.
- value: Error.InvalidCodeSignature
  description: The code signature of the app does not match the composed identifier,
    and the app cannot be managed.
- value: Error.IsSystemApp
  description: The app is a system app that cannot be managed.
- value: Error.LicenseNotFound
  description: A license for the app was not available.
- 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.UnmanagedAppAlreadyInstalled
  description: An unmanaged app is already installed and cannot be managed.
- value: Error.UserRejected
  description: The user rejected management of the app.
- value: Info.UpdateAvailable
  description: An update is available for the app.
- value: Error.UpdateFailed
  description: The app update failed.
  details:
  - key: Timestamp
    type: <string>
    valuetype: timestamp
    description: The RFC 3339 timestamp of the last update failure.
examples:
- title: Status item example
  files:
  - tab: New or updated app
    description: Reports a new or updated app.
    file: data/docc-examples/remotemanagementmodel/status/app.managed.list/example1.json
  - tab: Removed app
    description: Reports a removed app.
    file: data/docc-examples/remotemanagementmodel/status/app.managed.list/example2.json