Creates a Custom Script template that executes scripts on Windows target endpoints. The configuration is saved as a reusable template that can be deployed later. Supports repository scripts (executionType repository with scriptId) and inline commands (executionType commandLine with command). Script arguments are stored encrypted and can be hidden in the console with isMaskScriptArgs. Use the returned templateId with the Deploy Configuration Template API to deploy it to targets.
post /dcapi/config-policies/v2/windows/customScript
https://{serverurl}/dcapi/config-policies/v2/windows/customScript 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. Allowed values:
computer = applied to the endpoint
user = applied to the logged-on user
Reapply the configuration at every agent refresh, even when it has already been applied successfully.
Apply the configuration at endpoint startup when configType is computer, or at user logon when configType is user.
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.
The script to run. Exactly one entry is expected. Set executionType to repository and supply scriptId, or set it to commandLine and supply command.
File name of the repository script (e.g., "cleanup.bat"). Read only when executionType is Repository.
Command-line arguments passed to the script. Read only when executionType is Repository. Stored encrypted on Windows and as plain text on Mac.
Mask the arguments wherever they are shown in the console. Default: false
Description of what the script does, shown against the configuration in the console.
Comma-separated exit codes that count as a successful run (e.g., "0,1"). Any other code marks the deployment as failed.
How often the script runs. Allowed values:
once = runs it a single time
everyStartup = runs it at every endpoint startup
subsequentStartup = runs it for the next execCount startups
everyStartupUntil = runs it at every startup up to execExpTime
everyRefresh = runs it at every agent refresh
Matched case-insensitively. Default: "once"
Number of startups the script keeps running for. Read only when execFrequency is subsequentStartup.
Date and time the script stops running, in dd MMM yyyy, HH:mm:ss format. Read only when execFrequency is everyStartupUntil.
Write the script output to a log on the endpoint. Applies only when execFrequency is once. Default: false
Extra files the script needs at run time, each already uploaded through POST /emsapi/files and referenced here by fileID and fileName. Send an empty array when the script has no dependencies.
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 configuration file name.
Repository script identifier. Mandatory when executionType is Repository. Fetch it from List Scripts, or use the scriptId returned by Add New Script.
Command line to execute when executionType is CommandLine.
Where the script comes from. Allowed values:
Repository = runs a script already in the Script Repository and makes scriptId mandatory
CommandLine = runs the inline command in command and ignores scriptId, name and arguments
Matched case-insensitively.
Saved credential the script runs as, referenced by credentialID and credentialUUID from List Credentials. Always use an actual saved credential and avoid using credentialDetails: {credentialID: "-1", credentialName: "", credentialUUID: "--"}.
Identifier of a credential already saved under Admin - Credential Manager. Fetch it from List Credentials. Pass the credentialID together with its credentialUUID; the credential secret itself is never sent through this API.
UUID of the saved credential, used to reference it without transmitting the secret. Fetch it from List Credentials. Must correspond to the credentialID supplied alongside it.
Display name of the saved credential.
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/windows/customScript \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{}],"label":"Sample CUSTOM_SCRIPT Config","configType":"computer"}'Run a repository script once. executionType is repository, so scriptId is mandatory - take it from List Scripts or from the response of Add New Script.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Sample CUSTOM_SCRIPT Config",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"isMaskScriptArgs": false,
"scriptId": 101,
"scriptDescription": "Removes temporary files from the endpoint.",
"credentialDetails": {
"credentialUUID": "--",
"credentialID": -1,
"credentialName": ""
},
"execFrequency": "once",
"executionType": "repository",
"name": "cleanup.bat",
"dependencyFiles": [],
"exitCodes": "0",
"arguments": "-silent",
"enableLogging": true
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/windows/customScript \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{}],"label":"PowerShell Cleanup Script","configType":"computer"}'Run a PowerShell script from the repository at the next three startups. execFrequency is subsequentStartup, so execCount states how many startups the script runs for, and isMaskScriptArgs hides the arguments in the console.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "PowerShell Cleanup Script",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"isMaskScriptArgs": true,
"scriptId": 205,
"scriptDescription": "Purges files older than 30 days.",
"execFrequency": "subsequentStartup",
"executionType": "repository",
"name": "cleanup.ps1",
"execCount": 3,
"dependencyFiles": [],
"exitCodes": "0,1",
"arguments": "-Path C:\\Temp -Days 30",
"enableLogging": false
}
],
"enableNotification": false,
"enableEmailNotify": false,
"notificationDuration": 6,
"enableRetry": false,
"enableRefreshMinRetry": false,
"email": ""
}
curl --request POST \
--url https://appdomains/dcapi/config-policies/v2/windows/customScript \
--header 'Accept: application/json' \
--header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"configDetails":[{}],"label":"Restart Endpoint","configType":"computer"}'Run an inline command. executionType is commandLine, so command replaces scriptId and the script repository is not used.
{
"applyAtRefresh": false,
"applyAlways": false,
"description": "Created through the Config Policies API.",
"label": "Restart Endpoint",
"configType": "computer",
"applyAtStartupLogon": true,
"noOfRetries": 2,
"refreshMinRetry": 1,
"notificationEnabledDays": 3,
"enableLogonStartupMinRetry": false,
"logonStartupMinRetry": 1,
"configDetails": [
{
"execFrequency": "once",
"executionType": "commandLine",
"exitCodes": "0",
"enableLogging": false,
"command": "shutdown /r /t 0"
}
],
"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 deployCustomScript
{
"templateName": "deployCustomScript",
"templateId": 316,
"configType": "computer",
"addedUser": "admin"
}
Error response for deployCustomScript
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for powershellScript
{
"templateName": "powershellScript",
"templateId": 317,
"configType": "computer",
"addedUser": "admin"
}
Error response for powershellScript
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
Success response for commandLineScript
{
"templateName": "commandLineScript",
"templateId": 318,
"configType": "computer",
"addedUser": "admin"
}
Error response for commandLineScript - executionType is commandLine but command is missing
{
"errorCode": 50003,
"errorMsg": "Some Input field missing in configuration"
}
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/windows/customScript",
"errorMsg": "The URL /dcapi/config-policies/v2/windows/customScript 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.