Update computer or user targets by resource IDs

Updates the targets of an existing collection, configuration using numeric resource IDs.

Modes: Pass appendTargets=true to add to existing targets (APPEND). Omit this parameter to replace all targets (REPLACE). Note: REPLACE is not supported for user targets - use APPEND instead.

Scope validation: Each resource ID (Computer or User) must be within the technician's assigned scope. To look up resource IDs for collection, use ComputerDetails to get all computers. To use this endpoint, set useResourceIdFormat=true in the request body.

Endpoints

put /dcapi/target/{collectionId}/modifyTargets

Copy full URL

Request URL

https://{serverurl}/dcapi/target/{collectionId}/modifyTargets

Scope

DesktopCentralCloud.Configurations.UPDATE, DesktopCentralCloud.SWDeployment.UPDATE, DesktopCentralCloud.PatchMgmt.UPDATE, DesktopCentralCloud.VulnerabilityMgmt.UPDATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory

application/modifyTargets.v1+jsonCopied!

AcceptstringMandatory

application/modifyTargets.v1+jsonCopied!

- Path Parameters

collectionIdstringMandatory

The unique numeric identifier of the collection whose targets are to be updated. Fetch from Get Configurations View .

- Request Body

application/json

JSON Object

Hide Sub-Attributes

useResourceIdFormatbooleanOptional

Mandatory. Must be true to activate the new-format path. When false, use the 'targets' array (legacy path) instead.

appendTargetsbooleanOptional

Optional. When true, new targets are appended to the existing target list; duplicates are silently skipped. When false (default), existing targets are fully replaced by the supplied list.

targetDetailsJSON ObjectOptional

Mandatory when useResourceIdFormat=true. Target descriptor with type and resource IDs. Must NOT be combined with 'targets' in the same request.

Show Sub-Attributes

typestringOptional

Mandatory. Target category — 'computer' or 'user' (case-insensitive). Must match the collection's existing type; a mismatch returns a 400 error.

valuesarrayOptional

Mandatory. Array of numeric resource IDs to assign as targets. Each ID is validated against the RESOURCE table — computer IDs must be actively managed (MANAGED_BY_DC) and belong to the customer. Scoped technicians can only reference resources within their USERRESOURCEMAPPING scope. Any invalid, non-managed, or out-of-scope ID returns a 400 error. Minimum 1 entry.

isDomainMainTargetbooleanOptional

Optional. When true, the domain is used as the main target in the generated target payload instead of the remote office. Defaults to false.

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request PUT \
  --url https://appdomains/dcapi/target/{collectionId}/modifyTargets \
  --header 'Accept: application/modifyTargets.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/modifyTargets.v1+json' \
  --data '{}'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://appdomains/dcapi/target/{collectionId}/modifyTargets"))
        .header("Content-Type", "application/modifyTargets.v1+json")
        .header("Accept", "application/modifyTargets.v1+json")
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("PUT", HttpRequest.BodyPublishers.ofString("{}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("appdomains")

payload = "{}"

headers = {
    'Content-Type': "application/modifyTargets.v1+json",
    'Accept': "application/modifyTargets.v1+json",
    'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("PUT", "/dcapi/target/{collectionId}/modifyTargets", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Content-Type", "application/modifyTargets.v1+json");
    headersMap.put("Accept", "application/modifyTargets.v1+json");

    data=Map();

    response = invokeUrl
    [
        url: "https://appDomains/dcapi/target/{collectionId}/modifyTargets"
        type: PUT
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Content-Type", "application/modifyTargets.v1+json")
$headers.Add("Accept", "application/modifyTargets.v1+json")
$headers.Add("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomains/dcapi/target/{collectionId}/modifyTargets' -Method PUT -Headers $headers -ContentType 'application/modifyTargets.v1+json' -Body '{}'

Sample Request Body

Replace all targets for a computer-type collection with three resource IDs

Copied!

  {
    "appendTargets": false,
    "useResourceIdFormat": true,
    "targetDetails": {
      "isDomainMainTarget": false,
      "values": [
        1001,
        1002,
        1003
      ],
      "type": "computer"
    }
  }

▼ Show full

Append new user resource IDs to an existing user-type collection's target list

Copied!

  {
    "appendTargets": true,
    "useResourceIdFormat": true,
    "targetDetails": {
      "isDomainMainTarget": false,
      "values": [
        2005,
        2006
      ],
      "type": "user"
    }
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

collectionIdlong

The collection ID whose targets were updated. Fetch from Get Configurations View .

totalTargetsstring

Total number of assigned targets after the update operation (after APPEND merge or REPLACE).

modestring

Update mode applied — 'APPEND' when appendTargets=true, 'REPLACE' when appendTargets=false (default).

statusstring

Confirmation string — always 'Updated' on success.

- HTTP code 400

Response Body - application/json

JSON Object

Hide Sub-Attributes

error_codestring

CONFIG_INVALID_INPUT_DATA: request payload validation failed. Possible causes: missing required field (useResourceIdFormat, targetDetails, targets, type, or values); mutual-exclusivity violation (targets and targetDetails both supplied); unsupported target type (not 'computer' or 'user'); filter type mismatch between request and collection type; invalid, non-managed, or out-of-scope resource ID in values array; unresolved name/domain pair; or empty values array.

error_descriptionstring

Specific message describing the first validation failure encountered.

- 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 500

Response Body - application/json

JSON Object

Hide Sub-Attributes

error_codestring

CONFIG_INTERNAL_ERROR or SERVICE_NOT_AVAILABLE: unexpected failure during target resolution, target payload generation, or collection update.

error_descriptionstring

Message describing the internal server error. Contact your administrator.

Possible Response Codes

200HTTP code

400HTTP code

401HTTP code

500HTTP code

Sample Response: HTTP 200

REPLACE mode — targets fully replaced with the supplied IDs

Copied!

  {
    "mode": "REPLACE",
    "totalTargets": 3,
    "collectionId": 12345,
    "status": "Updated"
  }

▼ Show full

APPEND mode — new targets merged into the existing list

Copied!

  {
    "mode": "APPEND",
    "totalTargets": 7,
    "collectionId": 67890,
    "status": "Updated"
  }

▼ Show full

Sample Response: HTTP 400

One of the supplied resource IDs is invalid, non-managed, or out of the technician's scope

Copied!

  {
    "error_description": "Resource ID 9999 is invalid, not managed, or out of your scope.",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }

▼ Show full

The requested target type does not match the collection's existing type

Copied!

  {
    "error_description": "Filter type mismatch. Collection is of type 'Computer' but request contains type 'User'",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }

▼ Show full

Sample Response: HTTP 401

User lacks write role for this configuration type

Copied!

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

▼ Show full

Sample Response: HTTP 500

Unexpected failure during target payload generation or collection update

Copied!

  {
    "error_description": "Error validating resource IDs. Contact administrator.",
    "error_code": "CONFIG_INTERNAL_ERROR"
  }

▼ 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.