Create a reusable Wallpaper template for Mac endpoints.

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

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.

Request URL

https://{serverurl}/dcapi/config-policies/v2/mac/wallpaper Copied!

Scope

DesktopCentralCloud.Configurations.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/jsonapplication/jsonCopied!

Media type of the request body, as consumed by the endpoint.

AcceptstringMandatory
application/jsonapplication/jsonCopied!

Media type of the response body, as produced by the endpoint.

- Request Body

application/json
JSON Object
Hide Sub-Attributes
labelstringMandatory

Name of the configuration. Returned as templateName in the response.

descriptionstringOptional

Free-text description of the configuration. May be an empty string.

configTypestringMandatory

What the configuration is applied to. Must be user - Wallpaper applies to users only.

applyAlwaysbooleanOptional

Reapply the configuration at every agent refresh, even when it has already been applied successfully.

applyAtStartupLogonbooleanOptional

Apply the configuration at user logon.

applyAtRefreshbooleanOptional

Apply the configuration at the scheduled agent refresh.

enableRetrybooleanOptional

Retry the configuration on the endpoint when it fails. noOfRetries sets how many attempts are made.

enableRefreshMinRetrybooleanOptional

Honour refreshMinRetry as the minimum gap between two retries at refresh.

enableLogonStartupMinRetrybooleanOptional

Honour logonStartupMinRetry as the minimum gap between two retries at startup or logon.

noOfRetriesintegerOptional

Number of retry attempts made after a failure. Read only when enableRetry is true.

refreshMinRetryintegerOptional

Minimum number of minutes between two retries at refresh. Read only when enableRefreshMinRetry is true.

logonStartupMinRetryintegerOptional

Minimum number of minutes between two retries at startup or logon. Read only when enableLogonStartupMinRetry is true.

configDetailsJSON ArrayMandatory

Exactly one entry, carrying the macOS wallpaper settings applied for the user.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
setSameImageForLockScreenbooleanMandatory

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

wallpaperActionstringMandatory

Action to be performed for the wallpaper.
Allowed values:
new = Applies a new wallpaper.

wallpaperFileJSON ObjectMandatory

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

Show Sub-Attributes
fileIDlongMandatory

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.

fileNamestringOptional

Uploaded file name.

lockScreenFileJSON ObjectOptional

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

Show Sub-Attributes
fileIDlongMandatory

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.

fileNamestringOptional

Uploaded file name.

wallpaperFileLocationTypestringMandatory

Location type from which the wallpaper file should be retrieved.
Allowed values:
http = Retrieves the wallpaper from an uploaded file reference.

wallpaperPositionstringMandatory

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.

enableEmailNotifybooleanOptional

Send an email to the addresses listed in email once the deployment finishes.

enableNotificationbooleanOptional

Notify the endpoint user about this deployment. notificationDuration and notificationEnabledDays are read only when this is true.

emailstringOptional

Comma-separated email addresses notified about the deployment. May be an empty string when enableEmailNotify is false.

notificationDurationintegerOptional

How long a deployment notification stays on screen for the endpoint user. Read only when enableNotification is true.

notificationEnabledDaysintegerOptional

Number of days for which deployment notifications stay enabled. Read only when enableNotification is true.

Examples

Apply Wallpaper (macOS)▼
Apply Wallpaper (macOS) -- Apply a wallpaper and reuse it for the lock screen on macOS endpoints.
Apply Desktop-Only Wallpaper -- Apply a wallpaper on macOS endpoints without reusing the same image for the lock screen.
Apply Filled Wallpaper -- Apply a wallpaper on macOS endpoints with the fill position.
Apply Stretched Wallpaper -- Apply a wallpaper on macOS endpoints with the stretch position.
Apply Fitted Wallpaper -- Apply a wallpaper on macOS endpoints with the fit position.
Apply Separate Lock Screen Wallpaper -- Apply one image to the desktop and a different image to the lock screen on macOS endpoints.
Apply Alternate Centered Wallpaper -- Apply a centered wallpaper on macOS endpoints while reusing the same image for the lock screen.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Wallpaper (macOS)

Apply a wallpaper on macOS endpoints and reuse it for the lock screen. The example includes every configDetails field documented for the wallpaper policy.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Desktop-Only Wallpaper

Apply a wallpaper only to the desktop and leave the lock screen unchanged.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Filled Wallpaper

Apply a wallpaper in fill mode on macOS endpoints and reuse it for the lock screen.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Stretched Wallpaper

Apply a wallpaper on macOS endpoints with the stretch position and a separate lock screen image.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Fitted Wallpaper

Apply a wallpaper and fit it within the screen while maintaining its aspect ratio, then reuse it for the lock screen.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Separate Lock Screen Wallpaper

Apply different images to the desktop and lock screen on macOS endpoints.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
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"}'

Sample Request Body - Apply Alternate Centered Wallpaper

Apply a centered wallpaper on macOS endpoints while reusing the same image for the lock screen.

Copied!
  {
    "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": ""
  }
                
▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Success response returned when the configuration is saved as a reusable template.

Hide Sub-Attributes
templateIdlong

Unique identifier of the created template. Pass it to the Deploy Configuration Template API to deploy this template to targets.

templateNamestring

Name of the created template. It is the label sent in the request.

configTypestring

Type of configuration the template was created for. Allowed values:
computer
user

addedUserstring

Login name of the API user who created the template.

- HTTP code 400

Response Body - application/json
JSON Object

Error response when the request contains invalid or missing required fields.

Hide Sub-Attributes
errorCodelong

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.

errorMsgstring

Localised error message for the error code.

- HTTP code 401

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)

errorMsgstring

Authentication failure reason

- HTTP code 413

Response Body - application/json
JSON Object

Error response returned when the server does not have enough free disk space to store the configuration files.

Hide Sub-Attributes
errorCodelong

Product error code. 170013 = INTERNAL_SERVER_ERROR: raised by the storage pre-check before the template is saved.

errorMsgstring

Localised error message for the error code.

- HTTP code 429

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

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

errorMsgstring

Rate limit exceeded message with retry guidance

- HTTP code 500

Response Body - application/json
JSON Object

Error response returned when the template could not be saved because of an unexpected server error.

Hide Sub-Attributes
errorCodelong

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.

errorMsgstring

Localised error message for the error code.

Response Examples

Sample Response: HTTP 200 - Apply Wallpaper (macOS)

Success response for macWallpaper

Copied!
  {
    "templateName": "macWallpaper",
    "templateId": 338,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Apply Wallpaper (macOS)

Error response for macWallpaper

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Desktop-Only Wallpaper

Success response for desktopOnlyWallpaper

Copied!
  {
    "templateName": "desktopOnlyWallpaper",
    "templateId": 339,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Apply Desktop-Only Wallpaper

Error response for desktopOnlyWallpaper

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Filled Wallpaper

Success response for filledWallpaper

Copied!
  {
    "templateName": "filledWallpaper",
    "templateId": 340,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Stretched Wallpaper

Success response for stretchWallpaper

Copied!
  {
    "templateName": "stretchWallpaper",
    "templateId": 341,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Fitted Wallpaper

Success response for fitWallpaper

Copied!
  {
    "templateName": "fitWallpaper",
    "templateId": 342,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Separate Lock Screen Wallpaper

Success response for separateLockScreenWallpaper

Copied!
  {
    "templateName": "separateLockScreenWallpaper",
    "templateId": 343,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 200 - Apply Alternate Centered Wallpaper

Success response for alternateCenteredWallpaper

Copied!
  {
    "templateName": "alternateCenteredWallpaper",
    "templateId": 344,
    "configType": "user",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 401

User is not authorized to create the configuration policy

Copied!
  {
    "errorCode": 1001,
    "errorMsg": "Access denied - You are not allowed to access the requested resource."
  }
                
▼ Show full

Sample Response: HTTP 413

Storage pre-check rejected the request before the template was saved

Copied!
  {
    "errorCode": 170013,
    "errorMsg": "The server machine does not have sufficient disk space. Please free up space and try again."
  }
                
▼ Show full

Sample Response: HTTP 429

Request rejected because the caller exceeded the configured rate limit

Copied!
  {
    "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."
  }
                
▼ Show full

Sample Response: HTTP 500

Unexpected server error while saving the configuration as a template

Copied!
  {
    "errorCode": 1003,
    "errorMsg": "An Internal Error occurred, try again later."
  }
                
▼ Show full

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.