Deploy a configuration from a template

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 and deploys a new configuration from the specified template to the given targets. Optionally supports immediate deployment.

Request URL

https://{serverurl}/dcapi/configuration/deploy/template

Scope

DesktopCentralCloud.Configurations.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/deployConfigurationTemplate.v1+jsonapplication/deployConfigurationTemplate.v1+jsonCopied!
AcceptstringMandatory
application/configDeployTemplateStatus.v1+jsonapplication/configDeployTemplateStatus.v1+jsonCopied!

- Request Body

application/json
JSON Object
Hide Sub-Attributes
templateIdlongOptional

Mandatory. The unique ID of the configuration template to deploy. Fetch from List Configuration Templates .

targetsJSON ObjectOptional

Mandatory. Single target descriptor identifying where the configuration should be deployed. See child keys.

Show Sub-Attributes
typestringOptional

Mandatory. Target type. Must be one of (lowercase): computer, user, domain, custom-group, remote-office.

valuesarrayOptional

Mandatory. Array of numeric resource IDs corresponding to the chosen 'type' (resource IDs for computer/user, custom-group IDs, remote-office IDs, etc.). Maximum 200 IDs per request.

isDomainMainTargetbooleanOptional

Optional. Applies only when type=computer. When true, the configuration is deployed with the domain as the main target instead of the associated remote office. Defaults to false.

deployImmediatebooleanOptional

Optional. When true, the configuration is deployed immediately to all targets. When false (default), the configuration will be picked up by the agent in the next refresh cycle.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/configuration/deploy/template \
  --header 'Accept: application/configDeployTemplateStatus.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/deployConfigurationTemplate.v1+json' \
  --data '{}'

Sample Request Body

Deploy template immediately to specific computer resources

Copied!
  {
    "deployImmediate": true,
    "templateId": 2001,
    "targets": {
      "isDomainMainTarget": false,
      "values": [
        301,
        302,
        303
      ],
      "type": "computer"
    }
  }
                
Show full

Deploy template to a custom group (next agent refresh)

Copied!
  {
    "templateId": 2001,
    "targets": {
      "values": [
        9001,
        9002
      ],
      "type": "custom-group"
    }
  }
                
Show full

Response Parameters

- HTTP code 200

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

The unique ID of the newly created configuration collection from the template deployment.

collectionNamestring

Display name of the created configuration.

configTypestring

The configuration type (e.g., computer or user).

addedUserstring

Username of the technician who initiated the deployment.

- HTTP code 400

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

CONFIG_INVALID_INPUT_DATA: request payload is missing required fields (templateId, targets), or contains unsupported collectionType 2.

error_descriptionstring

Message describing the specific validation failure in the request payload.

- HTTP code 401

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

Unauthorized error code: credentials missing, expired, or invalid

errorMsgstring

Authentication failure reason

- HTTP code 413

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

CONFIG_INVALID_INPUT_DATA: server storage limit exceeded, unable to create the configuration from template.

error_descriptionstring

Message indicating insufficient storage space for the deployment.

- HTTP code 500

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

SERVICE_NOT_AVAILABLE: unexpected error during template resolution or configuration deployment.

error_descriptionstring

Message describing the internal server error encountered during deployment.

Possible Response Codes

200HTTP code
400HTTP code
401HTTP code
413HTTP code
500HTTP code

Sample Response: HTTP 200

Template deployed successfully creating a new configuration

Copied!
  {
    "configType": "computer",
    "collectionId": 50001,
    "addedUser": "admin",
    "collectionName": "Firewall_Policy_Win11"
  }
                
Show full

Sample Response: HTTP 400

Request payload missing required templateId field

Copied!
  {
    "error_description": "Required fields are missing in the request payload",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }
                
Show full

CollectionType 2 is not supported by this API

Copied!
  {
    "error_description": "The API does not support collectionType 2",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }
                
Show full

Sample Response: HTTP 401

User lacks required write role or scope

Copied!
  {
    "error_description": "Access denied - You are not allowed to access the requested resource.",
    "error_code": "UAC_UNAUTHORIZED"
  }
                
Show full

Sample Response: HTTP 413

Server storage limit exceeded

Copied!
  {
    "error_description": "Insufficient storage space to deploy the configuration",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }
                
Show full

Sample Response: HTTP 500

Unexpected failure during template deployment

Copied!
  {
    "error_description": "An unexpected error occurred. Please try again later.",
    "error_code": "SERVICE_NOT_AVAILABLE"
  }
                
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.