Creates a Wallpaper template to configure wallpaper settings for Mac users. This policy supports only user configurations, accepts uploaded wallpaper files only, requires wallpaperAction to be new, and requires lockScreenFile when setSameImageForLockScreen is false.
post /dcapi/config-policies/v2/mac/wallpaper
https://{serverurl}/dcapi/config-policies/v2/mac/wallpaper Copied!
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Media type of the request body, as consumed by the endpoint.
Media type of the response body, as produced by the endpoint.
Name of the configuration. Returned as templateName in the response.
Free-text description of the configuration. May be an empty string.
What the configuration is applied to. Must be user - Wallpaper applies to users only.
Reapply the configuration at every agent refresh, even when it has already been applied successfully.
Apply the configuration at user logon.
Apply the configuration at the scheduled agent refresh.
Retry the configuration on the endpoint when it fails. noOfRetries sets how many attempts are made.
Honour refreshMinRetry as the minimum gap between two retries at refresh.
Honour logonStartupMinRetry as the minimum gap between two retries at startup or logon.
Number of retry attempts made after a failure. Read only when enableRetry is true.
Minimum number of minutes between two retries at refresh. Read only when enableRefreshMinRetry is true.
Minimum number of minutes between two retries at startup or logon. Read only when enableLogonStartupMinRetry is true.
Exactly one entry, carrying the macOS wallpaper settings applied for the user.
Whether the same wallpaper image should be applied to the lock screen.
Allowed values:
true = Applies the same image to the lock screen.
false = Does not apply the same image to the lock screen and requires lockScreenFile.
Default: true
Action to be performed for the wallpaper.
Allowed values:
new = Applies a new wallpaper.
Wallpaper image file to be applied. Upload the file using POST /emsapi/files and reference the uploaded file using its fileID and fileName.
Supported file formats: .jpg, .png
Identifier of a file already uploaded to the server. Upload the file first (POST /emsapi/files) and pass the fileID returned by that call. A fileID that has expired from the temporary upload folder is rejected.
Uploaded file name.
Lock screen image file to be applied when setSameImageForLockScreen is false. Upload the file using POST /emsapi/files and reference the uploaded file using its fileID and fileName.
Supported file formats: .jpg, .png
Identifier of a file already uploaded to the server. Upload the file first (POST /emsapi/files) and pass the fileID returned by that call. A fileID that has expired from the temporary upload folder is rejected.
Uploaded file name.
Location type from which the wallpaper file should be retrieved.
Allowed values:
http = Retrieves the wallpaper from an uploaded file reference.
Position of the wallpaper on the desktop.
Allowed values:
center = Centers the image without resizing it.
stretch = Stretches the image to fill the desktop.
fit = Resizes the image while maintaining its aspect ratio within the desktop.
fill = Resizes the image to fill the desktop while maintaining its aspect ratio.
retainExistingSettings = Retains the existing wallpaper position.
Send an email to the addresses listed in email once the deployment finishes.
Notify the endpoint user about this deployment. notificationDuration and notificationEnabledDays are read only when this is true.
Comma-separated email addresses notified about the deployment. May be an empty string when enableEmailNotify is false.
How long a deployment notification stays on screen for the endpoint user. Read only when enableNotification is true.
Number of days for which deployment notifications stay enabled. Read only when enableNotification is true.
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":311},"wallpaperPosition":"center","setSameImageForLockScreen":true,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Mac Wallpaper Config","configType":"user"}'Apply a wallpaper on macOS endpoints and reuse it for the lock screen. The example includes every configDetails field documented for the wallpaper policy.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Mac Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "custom-wallpaper.png",
"fileID": 311
},
"wallpaperPosition": "center",
"setSameImageForLockScreen": true,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":312},"wallpaperPosition":"fill","setSameImageForLockScreen":false,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Desktop Wallpaper Only","configType":"user"}'Apply a wallpaper only to the desktop and leave the lock screen unchanged.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Desktop Wallpaper Only",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "branding-wallpaper.png",
"fileID": 312
},
"lockScreenFile": {
"fileName": "branding-lockscreen.png",
"fileID": 412
},
"wallpaperPosition": "fill",
"setSameImageForLockScreen": false,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":313},"wallpaperPosition":"fill","setSameImageForLockScreen":true,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Filled Wallpaper Config","configType":"user"}'Apply a wallpaper in fill mode on macOS endpoints and reuse it for the lock screen.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Filled Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "filled-wallpaper.png",
"fileID": 313
},
"wallpaperPosition": "fill",
"setSameImageForLockScreen": true,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":314},"wallpaperPosition":"stretch","setSameImageForLockScreen":false,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Stretched Wallpaper Config","configType":"user"}'Apply a wallpaper on macOS endpoints with the stretch position and a separate lock screen image.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Stretched Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "stretched-wallpaper.png",
"fileID": 314
},
"lockScreenFile": {
"fileName": "stretched-lockscreen.png",
"fileID": 414
},
"wallpaperPosition": "stretch",
"setSameImageForLockScreen": false,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":315},"wallpaperPosition":"fit","setSameImageForLockScreen":true,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Fitted Wallpaper Config","configType":"user"}'Apply a wallpaper and fit it within the screen while maintaining its aspect ratio, then reuse it for the lock screen.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Fitted Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "fit-wallpaper.png",
"fileID": 315
},
"wallpaperPosition": "fit",
"setSameImageForLockScreen": true,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":316},"wallpaperPosition":"center","setSameImageForLockScreen":false,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Separate Lock Screen Wallpaper Config","configType":"user"}'Apply different images to the desktop and lock screen on macOS endpoints.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Separate Lock Screen Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "desktop-wallpaper.png",
"fileID": 316
},
"lockScreenFile": {
"fileName": "lockscreen-wallpaper.png",
"fileID": 416
},
"wallpaperPosition": "center",
"setSameImageForLockScreen": false,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/mac/wallpaper \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{"wallpaperFile":{"fileID":317},"wallpaperPosition":"center","setSameImageForLockScreen":true,"wallpaperAction":"new","wallpaperFileLocationType":"http"}],"label":"Alternate Centered Wallpaper Config","configType":"user"}'Apply a centered wallpaper on macOS endpoints while reusing the same image for the lock screen.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Alternate Centered Wallpaper Config",
"configType": "user",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"wallpaperFile": {
"fileName": "alternate-wallpaper.png",
"fileID": 317
},
"wallpaperPosition": "center",
"setSameImageForLockScreen": true,
"wallpaperAction": "new",
"wallpaperFileLocationType": "http"
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
Success response returned when the configuration is saved as a reusable template.
Unique identifier of the created template. Pass it to the Deploy Configuration Template API to deploy this template to targets.
Name of the created template. It is the label sent in the request.
Type of configuration the template was created for. Allowed values:
computer
user
Login name of the API user who created the template.
Error response when the request contains invalid or missing required fields.
Product error code. 50003 = CONFIG_INVALID_INPUT_DATA: configDetails is missing or empty, or the configuration could not be resolved for this endpoint. 20003 = SERVICE_NOT_AVAILABLE: the configuration is deprecated for the requested configType.
Localised error message for the error code.
Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)
Authentication failure reason
Error response returned when the server does not have enough free disk space to store the configuration files.
Product error code. 170013 = INTERNAL_SERVER_ERROR: raised by the storage pre-check before the template is saved.
Localised error message for the error code.
Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes
Rate limit exceeded message with retry guidance
Error response returned when the template could not be saved because of an unexpected server error.
Product error code. 1003 = INTERNAL_ERROR: the template could not be persisted. 50001 = CONFIG_INTERNAL_ERROR: an internal configuration error occurred while processing the request.
Localised error message for the error code.
Success response for macWallpaper
{
"templateName": "macWallpaper",
"templateId": 338,
"configType": "user",
"addedUser": "admin"
}
Error response for macWallpaper
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for desktopOnlyWallpaper
{
"templateName": "desktopOnlyWallpaper",
"templateId": 339,
"configType": "user",
"addedUser": "admin"
}
Error response for desktopOnlyWallpaper
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for filledWallpaper
{
"templateName": "filledWallpaper",
"templateId": 340,
"configType": "user",
"addedUser": "admin"
}
Success response for stretchWallpaper
{
"templateName": "stretchWallpaper",
"templateId": 341,
"configType": "user",
"addedUser": "admin"
}
Success response for fitWallpaper
{
"templateName": "fitWallpaper",
"templateId": 342,
"configType": "user",
"addedUser": "admin"
}
Success response for separateLockScreenWallpaper
{
"templateName": "separateLockScreenWallpaper",
"templateId": 343,
"configType": "user",
"addedUser": "admin"
}
Success response for alternateCenteredWallpaper
{
"templateName": "alternateCenteredWallpaper",
"templateId": 344,
"configType": "user",
"addedUser": "admin"
}
User is not authorized to create the configuration policy
{
"errorCode": 1001,
"errorMsg": "Access denied - You are not allowed to access the requested resource."
}
Storage pre-check rejected the request before the template was saved
{
"errorCode": 170013,
"errorMsg": "The server machine does not have sufficient disk space. Please free up space and try again."
}
Request rejected because the caller exceeded the configured rate limit
{
"errorCode": "IAM0019",
"url": "/dcapi/config-policies/v2/mac/wallpaper",
"errorMsg": "The URL /dcapi/config-policies/v2/mac/wallpaper was called too many times. Please retry after a while."
}
Unexpected server error while saving the configuration as a template
{
"errorCode": 1003,
"errorMsg": "An Internal Error occurred, try again later."
}
![]()
Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes
Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.