Update computer or user targets using domain and value pairs

Updates the targets of an existing collection, configuration using domain and value pairs.

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 resources(Computer or User) must be within the technician's assigned scope. To look up resource Domain and name for collection, use ComputerDetails to get all computers. This is the default format. Omit useResourceIdFormat from the request body, or set it to false explicitly.

Endpoints

put /dcapi/target/{collectionId}/modifyTargets

Copy full URL

Request URL

https://{server-hostname}:8383/dcapi/target/{collectionId}/modifyTargets

Scope

Configurations.UPDATECopied!
(or)
SWDeployment.UPDATECopied!
(or)
PatchMgmt.UPDATECopied!
(or)
VulnerabilityMgmt.UPDATECopied!

Header

Authorization: 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 false (or omitted) to activate the legacy name/domain path. When true, use 'targetDetails' (Resource ID 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.

targetsJSON ArrayOptional

Mandatory when useResourceIdFormat=false. Array containing a single filter entry with name/domain pairs. Must NOT be combined with 'targetDetails'. Minimum 1 item; minimum 1 value inside filter.values.

Show Sub-Attributes

JSON Object

Show Sub-Attributes

filterJSON ObjectOptional

Mandatory. Filter object defining the target type and resource name/domain pairs.

Show Sub-Attributes

typestringOptional

Mandatory. Target category — 'Computer' or 'User'. Must match the collection's existing type; a mismatch returns a 400 error.

isDomainMainTargetbooleanOptional

Optional. When true, the domain is used as the main target in the generated target payload. Read from the first filter entry. Defaults to false.

valuesJSON ArrayOptional

Mandatory. Array of name/domain pair objects identifying resources to target. Each pair is resolved via a batched database lookup (1000 entries/batch); any unresolved pair returns a 400 error. Minimum 1 entry.

Show Sub-Attributes

JSON Object

Show Sub-Attributes

valuestringOptional

Mandatory. NetBIOS computer name or username of the target resource.

domainstringOptional

Mandatory. Active Directory domain or workgroup the target resource belongs to.

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request PUT \
  --url https://appdomain/dcapi/target/{collectionId}/modifyTargets \
  --header 'Accept: application/modifyTargets.v1+json' \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/modifyTargets.v1+json' \
  --data '{"appendTargets":false,"useResourceIdFormat":false,"targets":[{"filter":{"isDomainMainTarget":false,"values":[{"domain":"CORP","value":"PC-001"},{"domain":"CORP","value":"LAPTOP-DEF"}],"type":"Computer"}}]}'

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://appdomain/dcapi/target/{collectionId}/modifyTargets"))
        .header("Content-Type", "application/modifyTargets.v1+json")
        .header("Accept", "application/modifyTargets.v1+json")
        .header("Authorization", " d92d4xxxxxxxxxxxxx15f52")
        .method("PUT", HttpRequest.BodyPublishers.ofString("{\"appendTargets\":false,\"useResourceIdFormat\":false,\"targets\":[{\"filter\":{\"isDomainMainTarget\":false,\"values\":[{\"domain\":\"CORP\",\"value\":\"PC-001\"},{\"domain\":\"CORP\",\"value\":\"LAPTOP-DEF\"}],\"type\":\"Computer\"}}]}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

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

payload = "{\"appendTargets\":false,\"useResourceIdFormat\":false,\"targets\":[{\"filter\":{\"isDomainMainTarget\":false,\"values\":[{\"domain\":\"CORP\",\"value\":\"PC-001\"},{\"domain\":\"CORP\",\"value\":\"LAPTOP-DEF\"}],\"type\":\"Computer\"}}]}"

headers = {
    'Content-Type': "application/modifyTargets.v1+json",
    'Accept': "application/modifyTargets.v1+json",
    'Authorization': " 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();
    data.put("useResourceIdFormat",true);
    data.put("appendTargets",true);
    data_targets=List();
    data_targets_item1=Map();
    data_targets_item1_filter=Map();
    data_targets_item1_filter.put("type","value");
    data_targets_item1_filter.put("isDomainMainTarget",true);
    data_targets_item1_filter_values=List();
    data_targets_item1_filter_values_item1=Map();
    data_targets_item1_filter_values_item1.put("value","value");
    data_targets_item1_filter_values_item1.put("domain","value");
    data_targets_item1_filter_values.add(data_targets_item1_filter_values_item1);
    data_targets_item1_filter.put("values",data_targets_item1_filter_values);
    data_targets_item1.put("filter",data_targets_item1_filter);
    data_targets.add(data_targets_item1);
    data.put("targets",data_targets);

    response = invokeUrl
    [
        url: "https://appDomain/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", " d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomain/dcapi/target/{collectionId}/modifyTargets' -Method PUT -Headers $headers -ContentType 'application/modifyTargets.v1+json' -Body '{"appendTargets":false,"useResourceIdFormat":false,"targets":[{"filter":{"isDomainMainTarget":false,"values":[{"domain":"CORP","value":"PC-001"},{"domain":"CORP","value":"LAPTOP-DEF"}],"type":"Computer"}}]}'

Sample Request Body

Replace all targets for a computer-type collection using domain/value pairs

Copied!

  {
    "appendTargets": false,
    "useResourceIdFormat": false,
    "targets": [
      {
        "filter": {
          "isDomainMainTarget": false,
          "values": [
            {
              "domain": "CORP",
              "value": "PC-001"
            },
            {
              "domain": "CORP",
              "value": "LAPTOP-DEF"
            }
          ],
          "type": "Computer"
        }
      }
    ]
  }

▼ Show full

Append a new user target to an existing user-type collection

Copied!

  {
    "appendTargets": true,
    "useResourceIdFormat": false,
    "targets": [
      {
        "filter": {
          "isDomainMainTarget": false,
          "values": [
            {
              "domain": "CORP",
              "value": "jsmith"
            }
          ],
          "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 returned when authentication credentials are missing, expired, or invalid (authentication=required)

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 resolved domain/value pairs

Copied!

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

▼ Show full

APPEND mode — new targets merged into the existing list

Copied!

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

▼ Show full

Sample Response: HTTP 400

A domain/value pair could not be matched to any managed resource

Copied!

  {
    "error_description": "BADPC.CORP - Invalid target Value",
    "error_code": "CONFIG_INVALID_INPUT_DATA"
  }

▼ Show full

The targets array is empty

Copied!

  {
    "error_description": "'targets' array is empty",
    "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 resolution or collection update

Copied!

  {
    "error_description": "Error resolving targets. 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.