You are here: Home > API Reference > Apple > Policies > Update device policy

Update device policy

Required Permission: mdm.apple.policy.update

Updates the configuration, restrictions, and security settings for an existing policy.

PUT
https://api.applivery.io/v1/organizations/{organizationId}/mdm/apple/enterprise/policies/{admPolicyId}

Request

Send your API key in the request header authorization
Example: Authorization: Bearer <token>

organizationId string
required
Match pattern: ^(([a-fA-F0-9]{24})|([a-zA-Z0-9\\-]{3,}))$
admPolicyId string
required
Apple device policy unique identifier used in URL path for retrieving or modifying specific policy configuration.
Match pattern: ^[a-fA-F0-9]{24}$

Body Params application/json
name string optional
Human-readable policy name displayed in dashboard for administrative identification and organizational purposes throughout device management.
≤ 256 characters
description string optional
Optional free-text description clarifying the purpose or scope of this policy.
≤ 500 characters
profiles array [string] optional
List of configuration profile identifiers to attach to policy defining device restrictions and security settings.
applications array [object] optional
List of application assignments defining managed apps with VPP licensing installation actions and configuration settings.
admApplication string required
Apple application assignment target referencing the admApplication entity to install or expose on the device, policy, or enrollment token.
Match pattern: ^[a-fA-F0-9]{24}$
managed boolean optional
Controls Apple managed-install semantics for this app assignment. This field still drives InstallAsManaged and ChangeManagementState.
managementFlags number optional
Optional Apple MDM InstallApplication.ManagementFlags override for this app assignment. Supported values are 1 (remove app when the MDM profile is removed), 4 (prevent backup of app documents and data), and 5 (both behaviors). If omitted, backend behavior stays unchanged: managed=true sends 5; otherwise the field is omitted. This field only overrides Apple ManagementFlags and does not imply managed=true.
Format: float
0 1 4 5
vpp boolean optional
Enables Apple Volume Purchase Program purchase handling for this assignment when the app should be installed through VPP licensing.
iOSApp boolean optional
Apple InstallApplication iOSApp flag passed for this assignment when the target app should be treated as an iOS app payload.
configuration object optional
Managed app configuration object sent with the Apple app assignment when the application supports configuration keys.
action string optional
Assignment action defining whether the app is force-installed, available for optional install, or required during setup.
forceInstall available requiredForSetup
actionStatus string optional
Read-only effective assignment status shown in responses. Devices may report available assignments as either available or available-install depending on the device request state.
forceInstall available requiredForSetup available-install
scripts object optional
Optional agent-side install lifecycle scripts associated with this assignment for Apple agent-managed application flows.
preInstall string optional
postInstall string optional
audit string optional
enforce string optional
runner string optional
updatePolicy object optional
Quarantine and grace-period configuration for this app assignment. quarantine (0-30 days, a single value shared by all update types) holds a build back until it has been released for that many whole UTC days, but only when the agent config assets resolve which build to distribute (last build, last build on a git branch/tag, etc.): the previous build that already cleared the window is served instead. It never applies to an assignment pinned to a specific build, nor to the builds pushed over MDM. autoUpdate governs the grace periods: when it is true, each gracePeriod (0-90 days) becomes a graceExpirationDate — the start of the resolved build's release UTC day, plus quarantine, plus that gracePeriod — sent to the agent for that update type. When autoUpdate is false no grace dates are emitted, and when it has never been configured no update policy is sent at all, so the agent keeps its own default.
quarantine integer optional
≥ 0 · ≤ 30
autoUpdate boolean optional
major object optional
minor object optional
patch object optional
books array [object] optional
List of book assignments for distributing VPP-purchased books or PDF documents to managed Apple devices.
type string optional
asset store
id string optional
≤ 128 characters
scripts array [object] optional
List of script assignments for executing automated tasks compliance checks and configuration enforcement on macOS devices.
id string optional
≤ 128 characters
type string optional
once loop onDemand
loopTime integer optional
≥ 0
resetDate string optional
Format: date-time
arguments string optional
argumentsProcessed string optional
name string optional
≤ 256 characters
description string optional
≤ 500 characters
runner string optional
≤ 256 characters
scope string optional
user machine
bookmarks array [object] optional
List of bookmark assignments for deploying web application shortcuts and internal portal links to device home screens.
title string optional
≤ 256 characters
description string optional
≤ 500 characters
url string optional
≤ 500 characters
iconBase64 string optional
iconUrl string optional
≤ 500 characters
assets array [object] optional
List of asset assignments for deploying files certificates configuration data and resources to managed macOS devices.
mdmAssetId string optional
Match pattern: ^[a-fA-F0-9]{24}$
location string optional
≤ 256 characters
assetName string optional
≤ 256 characters
scope string optional
user system all-users
provisioningProfiles array [object] optional
Provisioning profiles to install on the devices targeted by this policy. Send the .mobileprovision or .provisionprofile file base64 encoded in content, optionally as a data URI; the UUID name expiration date and team identifier are extracted from the file server side. Duplicated files are assigned only once.
name string required
≤ 256 characters
content string required
uuid string optional
≤ 128 characters
agentConfiguration object optional
MDM agent behavior settings controlling location tracking app monitoring data collection and application enforcement actions.
allowLocation boolean optional
Flag enabling location tracking for iOS and iPadOS devices through MDM agent for geofencing and asset management.
allowLocationMacos boolean optional
Flag enabling location tracking for macOS devices through MDM agent requiring user privacy consent and system permissions.
allowPackageTime boolean optional
Default application usage time when platform-specific flags are unset; used as fallback for iOS (allowPackageTimeIos) and directly for macOS applicationsTime.
allowPackageTimeIos boolean optional
iOS and iPadOS application usage time tracking. When omitted, allowPackageTime applies.
allowPackageTransfer boolean optional
macOS per-app network transfer (agent network report).
allowPackageTransferIos boolean optional
iOS and iPadOS per-app network transfer (agent network report).
allowDeviceInfoBatteryUsage boolean optional
Flag enabling battery usage statistics collection per application for power consumption analysis and device health monitoring.
allowDeviceInfoBluetooth boolean optional
Flag enabling Bluetooth device discovery and connection monitoring for peripheral inventory and security compliance tracking.
allowDeviceInfoSystemInfo boolean optional
Flag enabling comprehensive system information collection including hardware specifications OS versions and installed software inventory.
allowDeviceInfoBatteryUsageIos boolean optional
allowDeviceInfoBluetoothIos boolean optional
allowDeviceInfoSystemInfoIos boolean optional
allowNetworkStatusMacos boolean optional
allowNetworkStatusIos boolean optional
appBlacklist array [object] optional
List of unauthorized applications to block or remove from managed devices for security compliance and acceptable use enforcement.
bundleId string optional
Application bundle identifier matching installed app for blacklist enforcement on iOS iPadOS and macOS platforms.
≤ 256 characters
action string optional
Enforcement action defining whether to block app launch or automatically remove application from managed device.
block remove
policyFeatures object optional
ios object optional
macos object optional
teamviewerRemoteConfiguration object optional
status string optional
Whether this policy explicitly turns TeamViewer remote support on or off for its devices. 'none' means the policy has no opinion and inherits the setting from a lower-priority policy in composition; 'enabled'/'disabled' are explicit decisions, with the first non-'none' policy (by priority) winning.
≤ 128 characters
none enabled disabled
rollout object optional
loopTime integer optional
How often (in seconds) devices re-run the rollout-capture script while waiting to enroll with TeamViewer. Falls back to the library default when not set. Minimum 60.
≥ 0
segmentId number optional
Segment identifier for scoping policy into an specific segment
Format: float
exposeToChildren boolean optional
{
    "name": "Corporate Security Policy - iOS",
    "description": "Baseline security policy applied to all corporate-owned iOS devices.",
    "profiles": [
        "698f42e5457fafa13d088794",
        "698f42e5457fafa13d088795"
    ],
    "applications": [
        {
            "admApplication": "698f42e5457fafa13d088794",
            "managed": true,
            "managementFlags": 5,
            "vpp": true,
            "iOSApp": true,
            "configuration": {},
            "action": "forceInstall",
            "actionStatus": "forceInstall",
            "scripts": {},
            "updatePolicy": {
                "quarantine": 7,
                "autoUpdate": true,
                "major": {
                    "gracePeriod": 30
                }
            }
        }
    ],
    "books": [
        {
            "type": "asset",
            "id": "698f42e5457fafa13d088794"
        }
    ],
    "scripts": [
        {
            "type": "loop",
            "id": "698f42e5457fafa13d088794",
            "loopTime": 3600,
            "arguments": "--verbose --check-compliance",
            "name": "Security Compliance Check",
            "description": "Validates device security posture against organizational standards",
            "runner": "bash"
        }
    ],
    "bookmarks": [
        {
            "title": "Employee Portal",
            "description": "Internal employee self-service portal",
            "url": "https://portal.company.com",
            "iconBase64": "",
            "iconUrl": "https://portal.company.com/icon.png"
        }
    ],
    "assets": [
        {
            "mdmAssetId": "698f41b2457fafa13d088793",
            "location": "/Library/Application Support/Company/config.json",
            "assetName": "App Configuration",
            "scope": "system"
        }
    ],
    "provisioningProfiles": [
        {
            "name": "Enterprise Distribution",
            "content": "MIIN...base64 encoded .mobileprovision..."
        }
    ],
    "agentConfiguration": {
        "allowLocation": true,
        "allowLocationMacos": true,
        "allowPackageTime": true,
        "allowPackageTimeIos": true,
        "allowPackageTransfer": true,
        "allowPackageTransferIos": true,
        "allowDeviceInfoBatteryUsage": true,
        "allowDeviceInfoBluetooth": true,
        "allowDeviceInfoSystemInfo": true,
        "allowDeviceInfoBatteryUsageIos": true,
        "allowDeviceInfoBluetoothIos": true,
        "allowDeviceInfoSystemInfoIos": true,
        "allowNetworkStatusMacos": true,
        "allowNetworkStatusIos": true,
        "appBlacklist": [
            {
                "bundleId": "com.example.unauthorized",
                "action": "block"
            }
        ],
        "policyFeatures": {
            "ios": {
                "defaultViewFeature": "applications",
                "toggledFeatures": [
                    {
                        "name": "applications",
                        "active": true
                    }
                ],
                "enableDefaultView": true
            },
            "macos": {
                "defaultViewFeature": "applications",
                "toggledFeatures": [
                    {
                        "name": "applications",
                        "active": true
                    }
                ],
                "enableDefaultView": true
            }
        }
    },
    "teamviewerRemoteConfiguration": {
        "status": "enabled",
        "rollout": {
            "loopTime": 3600
        }
    },
    "segmentId": "1",
    "exposeToChildren": true
}

Responses

200 Response application/json
status boolean optional
data object optional
id string optional
Unique Apple device policy identifier used to track configuration rules and security settings throughout lifecycle.
Match pattern: ^[a-fA-F0-9]{24}$
organization string optional
Organization identifier owning this Apple device policy and managing enrolled iOS iPadOS and macOS devices.
Match pattern: ^[a-fA-F0-9]{24}$
admEnterprise string optional
Apple enterprise account identifier linked to Apple Business Manager or Apple School Manager for device management.
Match pattern: ^[a-fA-F0-9]{24}$
targetType string optional
Policy application scope defining whether configurations apply to entire device or device user context only.
device deviceUser
attachedProfile object optional
Automatically attached configuration profile containing essential MDM settings applied independently of policy assignments and priorities.
name string optional
Human-readable policy name displayed in dashboard for administrative identification and organizational purposes throughout device management.
≤ 256 characters
description string optional
Optional free-text description clarifying the purpose or scope of this policy.
≤ 500 characters
profiles array [object] optional
List of Apple configuration profiles containing device restrictions security settings and feature configurations applied by policy.
id string optional
Match pattern: ^[a-fA-F0-9]{24}$
organization string optional
Match pattern: ^[a-fA-F0-9]{24}$
admEnterprise string optional
Match pattern: ^[a-fA-F0-9]{24}$
admPolicy string optional
Match pattern: ^[a-fA-F0-9]{24}$
targetType string optional
device deviceUser
name string optional
≤ 256 characters
config object optional
certificates array [object] optional
type string optional
attached single internal
UUID string optional
≤ 128 characters
version integer optional
≥ 0
updatedAt string optional
Format: date-time
createdAt string optional
Format: date-time
assignedTo object optional
useCustomFileVaultCertificates boolean optional
parentAdmProfileId string optional
Match pattern: ^[a-fA-F0-9]{24}$
applications array [object] optional
List of application assignments defining managed apps with VPP licensing installation actions and configuration settings.
admApplication string required
Apple application assignment target referencing the admApplication entity to install or expose on the device, policy, or enrollment token.
Match pattern: ^[a-fA-F0-9]{24}$
managed boolean optional
Controls Apple managed-install semantics for this app assignment. This field still drives InstallAsManaged and ChangeManagementState.
managementFlags number optional
Optional Apple MDM InstallApplication.ManagementFlags override for this app assignment. Supported values are 1 (remove app when the MDM profile is removed), 4 (prevent backup of app documents and data), and 5 (both behaviors). If omitted, backend behavior stays unchanged: managed=true sends 5; otherwise the field is omitted. This field only overrides Apple ManagementFlags and does not imply managed=true.
Format: float
0 1 4 5
vpp boolean optional
Enables Apple Volume Purchase Program purchase handling for this assignment when the app should be installed through VPP licensing.
iOSApp boolean optional
Apple InstallApplication iOSApp flag passed for this assignment when the target app should be treated as an iOS app payload.
configuration object optional
Managed app configuration object sent with the Apple app assignment when the application supports configuration keys.
action string optional
Assignment action defining whether the app is force-installed, available for optional install, or required during setup.
forceInstall available requiredForSetup
actionStatus string optional
Read-only effective assignment status shown in responses. Devices may report available assignments as either available or available-install depending on the device request state.
forceInstall available requiredForSetup available-install
scripts object optional
Optional agent-side install lifecycle scripts associated with this assignment for Apple agent-managed application flows.
updatePolicy object optional
Quarantine and grace-period configuration for this app assignment. quarantine (0-30 days, a single value shared by all update types) holds a build back until it has been released for that many whole UTC days, but only when the agent config assets resolve which build to distribute (last build, last build on a git branch/tag, etc.): the previous build that already cleared the window is served instead. It never applies to an assignment pinned to a specific build, nor to the builds pushed over MDM. autoUpdate governs the grace periods: when it is true, each gracePeriod (0-90 days) becomes a graceExpirationDate — the start of the resolved build's release UTC day, plus quarantine, plus that gracePeriod — sent to the agent for that update type. When autoUpdate is false no grace dates are emitted, and when it has never been configured no update policy is sent at all, so the agent keeps its own default.
applicationsInfo array [object] optional
Enriched application metadata including app names icons versions and store information for dashboard display purposes.
books array [object] optional
List of book assignments for distributing VPP-purchased books or PDF documents to managed Apple devices.
type string optional
asset store
id string optional
≤ 128 characters
booksInfo array [object] optional
Enriched book metadata including titles authors cover images and store information for dashboard display purposes.
scripts array [object] optional
List of script assignments for executing automated tasks compliance checks and configuration enforcement on macOS devices.
id string optional
≤ 128 characters
type string optional
once loop onDemand
loopTime integer optional
≥ 0
resetDate string optional
Format: date-time
arguments string optional
argumentsProcessed string optional
name string optional
≤ 256 characters
description string optional
≤ 500 characters
runner string optional
≤ 256 characters
scope string optional
user machine
scriptsInfo array [object] optional
Enriched script metadata including execution history last run timestamps and success rates for monitoring purposes.
bookmarks array [object] optional
List of bookmark assignments for deploying web application shortcuts and internal portal links to device home screens.
title string optional
≤ 256 characters
description string optional
≤ 500 characters
url string optional
≤ 500 characters
iconBase64 string optional
iconUrl string optional
≤ 500 characters
assets array [object] optional
List of asset assignments for deploying files certificates configuration data and resources to managed macOS devices.
mdmAssetId string optional
Match pattern: ^[a-fA-F0-9]{24}$
location string optional
≤ 256 characters
assetName string optional
≤ 256 characters
scope string optional
user system all-users
assetsInfo array [object] optional
Enriched asset metadata including file sizes deployment status and version information for monitoring and auditing purposes.
provisioningProfiles array [object] optional
Provisioning profiles assigned by this policy. The file content is masked here; use contentHash to detect changes or the retrieve provisioning profile endpoint to get the full content.
name string optional
≤ 256 characters
uuid string optional
≤ 128 characters
profileName string optional
≤ 256 characters
expirationDate string optional
Format: date-time
teamIdentifier string optional
≤ 128 characters
contentHash string optional
≤ 128 characters
contentLength integer optional
≥ 0
content string optional
agentConfiguration object optional
MDM agent behavior settings controlling location tracking app monitoring data collection and application enforcement actions.
allowLocation boolean optional
Flag enabling location tracking for iOS and iPadOS devices through MDM agent for geofencing and asset management.
allowLocationMacos boolean optional
Flag enabling location tracking for macOS devices through MDM agent requiring user privacy consent and system permissions.
allowPackageTime boolean optional
Default application usage time when platform-specific flags are unset; used as fallback for iOS (allowPackageTimeIos) and directly for macOS applicationsTime.
allowPackageTimeIos boolean optional
iOS and iPadOS application usage time tracking. When omitted, allowPackageTime applies.
allowPackageTransfer boolean optional
macOS per-app network transfer (agent network report).
allowPackageTransferIos boolean optional
iOS and iPadOS per-app network transfer (agent network report).
allowDeviceInfoBatteryUsage boolean optional
Flag enabling battery usage statistics collection per application for power consumption analysis and device health monitoring.
allowDeviceInfoBluetooth boolean optional
Flag enabling Bluetooth device discovery and connection monitoring for peripheral inventory and security compliance tracking.
allowDeviceInfoSystemInfo boolean optional
Flag enabling comprehensive system information collection including hardware specifications OS versions and installed software inventory.
allowDeviceInfoBatteryUsageIos boolean optional
allowDeviceInfoBluetoothIos boolean optional
allowDeviceInfoSystemInfoIos boolean optional
allowNetworkStatusMacos boolean optional
allowNetworkStatusIos boolean optional
appBlacklist array [object] optional
List of unauthorized applications to block or remove from managed devices for security compliance and acceptable use enforcement.
policyFeatures object optional
teamviewerRemoteConfiguration object optional
status string optional
Whether this policy explicitly turns TeamViewer remote support on or off for its devices. 'none' means the policy has no opinion and inherits the setting from a lower-priority policy in composition; 'enabled'/'disabled' are explicit decisions, with the first non-'none' policy (by priority) winning.
≤ 128 characters
none enabled disabled
rollout object optional
segmentId integer optional
Segment identifier for scoping policy into an specific segment
≥ 0
exposeToChildren boolean optional
createdAt string optional
ISO timestamp when policy was created in system for lifecycle tracking and compliance reporting purposes.
Format: date-time
updatedAt string optional
ISO timestamp of last policy modification for change tracking synchronization and audit trail purposes.
Format: date-time
version integer optional
Policy version number incremented with each modification for tracking configuration changes and rollback capabilities.
≥ 0
{
    "status": true,
    "data": {
        "id": "698f41b2457fafa13d088793",
        "organization": "598f469d457fafa13d088795",
        "admEnterprise": "698f42e5457fafa13d088794",
        "targetType": "device",
        "attachedProfile": {},
        "name": "Corporate Security Policy - iOS",
        "description": "Baseline security policy applied to all corporate-owned iOS devices.",
        "profiles": [
            {
                "id": "string",
                "organization": "string",
                "admEnterprise": "string",
                "admPolicy": "string",
                "targetType": "device",
                "name": "string",
                "config": {},
                "certificates": [
                    {
                        "mdmAssetId": "string",
                        "format": {
                            "uuid": "uuid",
                            "base64": "base64"
                        },
                        "location": "string",
                        "password": "string",
                        "allowAllAppsAccess": true,
                        "keyIsExtractable": true
                    }
                ],
                "type": "attached",
                "UUID": "string",
                "version": 0,
                "updatedAt": "2024-01-01T00: 00:00Z",
                "createdAt": "2024-01-01T00: 00:00Z",
                "assignedTo": {
                    "policies": [
                        {
                            "id": "string",
                            "name": "string"
                        }
                    ],
                    "devices": [
                        {
                            "id": "string",
                            "displayName": "string"
                        }
                    ]
                },
                "useCustomFileVaultCertificates": true,
                "parentAdmProfileId": "string"
            }
        ],
        "applications": [
            {
                "admApplication": "698f42e5457fafa13d088794",
                "managed": true,
                "managementFlags": 5,
                "vpp": true,
                "iOSApp": true,
                "configuration": {},
                "action": "forceInstall",
                "actionStatus": "forceInstall",
                "scripts": {},
                "updatePolicy": {
                    "quarantine": 7,
                    "autoUpdate": true,
                    "major": {
                        "gracePeriod": 30
                    }
                }
            }
        ],
        "applicationsInfo": [
            {}
        ],
        "books": [
            {
                "type": "asset",
                "id": "698f42e5457fafa13d088794"
            }
        ],
        "booksInfo": [
            {}
        ],
        "scripts": [
            {
                "type": "loop",
                "id": "698f42e5457fafa13d088794",
                "loopTime": 3600,
                "arguments": "--verbose --check-compliance",
                "name": "Security Compliance Check",
                "description": "Validates device security posture against organizational standards",
                "runner": "bash"
            }
        ],
        "scriptsInfo": [
            {}
        ],
        "bookmarks": [
            {
                "title": "Employee Portal",
                "description": "Internal employee self-service portal",
                "url": "https://portal.company.com",
                "iconBase64": "",
                "iconUrl": "https://portal.company.com/icon.png"
            }
        ],
        "assets": [
            {
                "mdmAssetId": "698f41b2457fafa13d088793",
                "location": "/Library/Application Support/Company/config.json",
                "assetName": "App Configuration",
                "scope": "system"
            }
        ],
        "assetsInfo": [
            {}
        ],
        "provisioningProfiles": [
            {
                "name": "Enterprise Distribution",
                "uuid": "2266b732-e799-4620-8d2c-a7bfdbb21334",
                "profileName": "Applivery Universal Distribution",
                "expirationDate": "2027-02-13T10: 00:00Z",
                "teamIdentifier": "ABCDE12345",
                "contentHash": "d41d8cd98f00b204e9800998ecf8427e",
                "contentLength": 12480,
                "content": "MIINnQYJKo...s6Gg8Yz3wQ"
            }
        ],
        "agentConfiguration": {
            "allowLocation": true,
            "allowLocationMacos": true,
            "allowPackageTime": true,
            "allowPackageTimeIos": true,
            "allowPackageTransfer": true,
            "allowPackageTransferIos": true,
            "allowDeviceInfoBatteryUsage": true,
            "allowDeviceInfoBluetooth": true,
            "allowDeviceInfoSystemInfo": true,
            "allowDeviceInfoBatteryUsageIos": true,
            "allowDeviceInfoBluetoothIos": true,
            "allowDeviceInfoSystemInfoIos": true,
            "allowNetworkStatusMacos": true,
            "allowNetworkStatusIos": true,
            "appBlacklist": [
                {
                    "bundleId": "com.example.unauthorized",
                    "action": "block"
                }
            ],
            "policyFeatures": {
                "ios": {
                    "defaultViewFeature": "applications",
                    "toggledFeatures": [
                        {
                            "name": "applications",
                            "active": true
                        }
                    ],
                    "enableDefaultView": true
                },
                "macos": {
                    "defaultViewFeature": "applications",
                    "toggledFeatures": [
                        {
                            "name": "applications",
                            "active": true
                        }
                    ],
                    "enableDefaultView": true
                }
            }
        },
        "teamviewerRemoteConfiguration": {
            "status": "enabled",
            "rollout": {
                "loopTime": 3600
            }
        },
        "segmentId": "1",
        "exposeToChildren": true,
        "createdAt": "2026-02-13T10: 00:00Z",
        "updatedAt": "2026-02-13T14: 30:00Z",
        "version": 3
    }
}
400 Response application/json
status boolean optional
false
error object optional
code number optional
5244
message string optional
The same provisioning profile is assigned more than once
{
    "status": false,
    "error": {
        "code": 5086,
        "message": "Attached adm profiles can not be added"
    }
}
401 Response application/json
status boolean optional
false
error object optional
code number optional
4004
message string optional
Invalid Token
{
    "status": false,
    "error": {
        "code": 4002,
        "message": "No auth token"
    }
}
404 Response application/json
status boolean optional
false
error object optional
code number optional
3001
message string optional
Entity not found
{
    "status": false,
    "error": {
        "code": 3001,
        "message": "Entity not found"
    }
}
Was this page helpful?