Create a reusable IP Printer template for Windows 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 an IP Printer template to set up IP-based printers on Windows target endpoints. This policy supports both computer and user configurations, but setting an IP printer as the default printer is supported only for user configurations.

Request URL

https://{serverurl}/dcapi/config-policies/v2/windows/ipPrinter 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. Allowed values:
computer = applied to the endpoint
user = applied to the logged-on user

IP Printer supports both computer and user configurations. setAsDefault is supported only when configType is user.

applyAlwaysbooleanOptional

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

applyAtStartupLogonbooleanOptional

Apply the configuration at endpoint startup when configType is computer, or at user logon when configType is user.

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

One entry per IP printer to add or remove, applied in the order they appear. IP Printer supports both computer and user configurations; setAsDefault is supported only for user configurations.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
actionstringMandatory

Determines how the IP printer entry is managed.
Allowed values:
add = Registers a new IP printer.
delete = Removes an existing IP printer.
Example: action: "add".

deleteAllIPPrinterbooleanOptional

Whether all configured IP printers should be deleted.
Allowed values:
true = Deletes all IP printers.
false = Deletes only the specified IP printer.

dnsNameOrIPstringOptional

DNS name or IP address of the IP printer.
Example: dnsNameOrIP: "192.168.1.100".

printerDisplayNamestringOptional

Display name of the IP printer.
Example: printerDisplayName: "Office Laser Printer".

protocolstringOptional

Communication protocol to be used for the IP printer.
Allowed values: RAW, LPR
Example: protocol: "RAW".

portNumberintegerOptional

Port number used to communicate with the IP printer.
Example: portNumber: 9100.

portNamestringOptional

Name of the printer port to be used for the IP printer.
Example: portName: "IP_192.168.1.100".

overWritebooleanOptional

Whether an existing printer configuration should be overwritten.
Allowed values:
true = Overwrites the existing printer configuration.
false = Retains the existing printer configuration.

setAsDefaultbooleanOptional

Whether the IP printer should be set as the default printer. This setting is supported only for user configurations.
Allowed values:
true = Sets the IP printer as the default printer for the user.
false = Does not set the IP printer as the default printer.
For computer configurations, omit this field or set it to false.

driverTypestringOptional

Type of printer driver to be used.
Allowed values:
newDriver = Uses a new printer driver supplied with the configuration.
preInstalledDriver = Uses a printer driver that is already installed on the computer.
sharedNetworkPrinter = Uses the driver associated with a shared network printer.
Example: driverType: "newDriver".

driverFileJSON ObjectOptional

Printer driver file to be used for the IP printer. Upload the driver file using POST /emsapi/files and reference the uploaded file using its fileID and fileName
Supported file formats: .exe, .zip

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.

driverNamestringOptional

Name of the printer driver to be used for the IP printer.
Example: driverName: "Generic Printer Driver".

infFileListarray[string]Optional

List of INF files required for installing the printer driver.

infFilestringOptional

Path to the INF file required to install the printer driver.
This field is enabled when driverType = "newDriver"
Example: infFile: "C:\Drivers\Printer\driver.inf".

sharedPrinterPathstringOptional

Path of the shared network printer.
Example: sharedPrinterPath: "\PrintServer\OfficePrinter".

useCredentialbooleanOptional

Whether credentials should be used when connecting to the printer.
Allowed values:
true = Uses the specified credentials.
false = Does not use credentials.

credentialDetailsJSON ObjectOptional

Credentials required to connect to the printer or shared printer location. Always use an actual saved credential and avoid using credentialDetails: {credentialID: "-1", credentialName: "", credentialUUID: "--"}.

Show Sub-Attributes
credentialIDlongOptional

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.

credentialUUIDstringOptional

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.

credentialNamestringOptional

Display name of the saved credential.

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

Add IP Printer▼
Add IP Printer -- Add an IP printer with a supplied driver and authentication settings; setAsDefault is supported only for user configurations.
Delete IP Printer -- Remove one configured IP printer by its display name.
Delete All IP Printers -- Remove all configured IP printers from the target endpoints.
Add Printer with Installed Driver -- Add an IP printer that uses a driver already installed on the endpoint.
Add Shared Network Printer -- Add an IP printer that uses the driver from a shared network printer path.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/ipPrinter \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"add"}],"label":"User IP Printer Config","configType":"user"}'

Sample Request Body - Add IP Printer

Configure one user-scoped IP printer entry with every documented field. setAsDefault is supported only when configType is user.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "User IP Printer Config",
    "configType": "user",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "driverFile": {
          "fileName": "PrinterDriver.zip",
          "fileID": 308
        },
        "useCredential": true,
        "infFileList": [
          "driver.inf",
          "printer.inf"
        ],
        "printerDisplayName": "Office Laser Printer",
        "deleteAllIPPrinter": false,
        "portName": "IP_192.168.1.100",
        "driverType": "newDriver",
        "portNumber": 9100,
        "setAsDefault": true,
        "dnsNameOrIP": "192.168.1.100",
        "protocol": "RAW",
        "credentialDetails": {
          "credentialUUID": "d97325aa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "credentialID": 301,
          "credentialName": "CONFIG PRINTER"
        },
        "action": "add",
        "driverName": "Generic Printer Driver",
        "infFile": "C:\\Drivers\\Printer\\driver.inf",
        "overWrite": true,
        "sharedPrinterPath": "\\\\PrintServer\\OfficePrinter"
      }
    ],
    "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/windows/ipPrinter \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"delete"}],"label":"Delete One IP Printer","configType":"computer"}'

Sample Request Body - Delete IP Printer

Delete one configured IP printer without removing the others. action delete with deleteAllIPPrinter false uses printerDisplayName to identify the printer entry to remove.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Delete One IP Printer",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "printerDisplayName": "Office Laser Printer",
        "action": "delete",
        "deleteAllIPPrinter": false
      }
    ],
    "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/windows/ipPrinter \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"delete"}],"label":"Delete All IP Printers","configType":"computer"}'

Sample Request Body - Delete All IP Printers

Delete every configured IP printer from the endpoint.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Delete All IP Printers",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "action": "delete",
        "deleteAllIPPrinter": true
      }
    ],
    "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/windows/ipPrinter \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"add"}],"label":"Installed Driver Printer Config","configType":"computer"}'

Sample Request Body - Add Printer with Installed Driver

Add an IP printer using a printer driver that is already installed on the endpoint.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Installed Driver Printer Config",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "dnsNameOrIP": "192.168.10.45",
        "protocol": "RAW",
        "printerDisplayName": "Finance Laser Printer",
        "action": "add",
        "driverName": "HP Universal Printing PCL 6",
        "deleteAllIPPrinter": false,
        "portName": "IP_192.168.10.45",
        "driverType": "preInstalledDriver",
        "portNumber": 9100,
        "overWrite": false,
        "setAsDefault": false
      }
    ],
    "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/windows/ipPrinter \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"add"}],"label":"Shared Network Printer Config","configType":"computer"}'

Sample Request Body - Add Shared Network Printer

Add an IP printer that uses the driver already published by a shared network printer. driverType sharedNetworkPrinter requires sharedPrinterPath and can optionally use saved credentials.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Shared Network Printer Config",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "useCredential": true,
        "printerDisplayName": "Shared Hallway Printer",
        "deleteAllIPPrinter": false,
        "portName": "IP_192.168.20.25",
        "driverType": "sharedNetworkPrinter",
        "portNumber": 9100,
        "setAsDefault": false,
        "dnsNameOrIP": "192.168.20.25",
        "protocol": "RAW",
        "credentialDetails": {
          "credentialUUID": "d97325aa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "credentialID": 301,
          "credentialName": "CONFIG PRINTER"
        },
        "action": "add",
        "overWrite": true,
        "sharedPrinterPath": "\\\\PrintServer\\HallwayPrinter"
      }
    ],
    "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 - Add IP Printer

Success response for addIpPrinter

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

Sample Response: HTTP 400 - Add IP Printer

Error response for addIpPrinter

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

Sample Response: HTTP 200 - Delete IP Printer

Success response for deleteIpPrinter

Copied!
  {
    "templateName": "deleteIpPrinter",
    "templateId": 359,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Delete IP Printer

Error response for deleteIpPrinter

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

Sample Response: HTTP 200 - Delete All IP Printers

Success response for deleteAllIpPrinters

Copied!
  {
    "templateName": "deleteAllIpPrinters",
    "templateId": 348,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Delete All IP Printers

Error response for deleteAllIpPrinters

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

Sample Response: HTTP 200 - Add Printer with Installed Driver

Success response for addPrinterWithInstalledDriver

Copied!
  {
    "templateName": "addPrinterWithInstalledDriver",
    "templateId": 357,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Add Printer with Installed Driver

Error response for addPrinterWithInstalledDriver

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

Sample Response: HTTP 200 - Add Shared Network Printer

Success response for addSharedNetworkPrinter

Copied!
  {
    "templateName": "addSharedNetworkPrinter",
    "templateId": 360,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Add Shared Network Printer

Error response for addSharedNetworkPrinter

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ 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/windows/ipPrinter",
    "errorMsg": "The URL /dcapi/config-policies/v2/windows/ipPrinter 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.