Update an existing remote office

Updates an existing remote office identified by ID. Supports modifying DS details, proxy settings, replication policy, and auto-install options.

Endpoints

put /dcapi/som/remote-offices/{remote_office_id}

Copy full URL

Request URL

https://{server-hostname}:8383/dcapi/som/remote-offices/{remote_office_id}

Scope

SOM.UPDATECopied!

Header

Authorization: d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory

application/remoteOfficeDetails.v1+jsonCopied!

AcceptstringMandatory

application/remoteOfficeUpdateStatus.v1+jsonCopied!

- Path Parameters

remote_office_idstringMandatory

Unique identifier for the remote office, get remote office id from Get Remote Offices resource_id field in response

- Request Body

application/json

JSON Object

Hide Sub-Attributes

remoteOfficeIDstringOptional

Specifies the unique identifier of the remote office. Required only for update operations; not applicable for create operations

remoteOfficeNamestringOptional

Administrator-defined display name for the remote office

descriptionstringOptional

Optional administrator-provided description for the remote office (max 250 characters)

agentCommunicationstringOptional

Protocol for agent-to-server communication. Allowed values: 'HTTPS'

uniqueServiceIDstringOptional

Tracking identifier for the computer modification operation. When creating, provide the current time in milliseconds. When updating, retrieve this value from the Unique Service ID

isProxyDefinedbooleanOptional

Set to true to configure a proxy server for agent communication in this remote office. When true, the proxyDetails object is required

proxyDetailsJSON ObjectOptional

Proxy server configuration including hostname, port, and authentication credentials

Show Sub-Attributes

proxyHoststringOptional

Hostname or IP address of the proxy server used for agent-to-server communication

proxyPortstringOptional

Port number on which the proxy server listens for connections

proxyUsernamestringOptional

Username for authenticating with the proxy server. Leave empty if the proxy does not require authentication

proxyPasswordstringOptional

Password for authenticating with the proxy server. Leave empty if the proxy does not require authentication

hasDSbooleanOptional

Set to true to associate a Distribution Server with this remote office. When true, the dsDetails object is required

dsDetailsJSON ObjectOptional

Distribution Server configuration including hostname, domain, IP addresses, and communication port

Show Sub-Attributes

domainNetbiosNamestringOptional

NetBIOS name of the Active Directory domain where the Distribution Server resides

dsNamestringOptional

Hostname of the computer where the Distribution Server is or will be installed

dsIPAddressJSON ArrayMandatory

Array of IP addresses assigned to the Distribution Server. At least one IP address is required

Show Sub-Attributes

string

dsDNSNamestringOptional

Fully qualified DNS name of the Distribution Server (e.g., 'DS-NYC-01.corp.local')

dsHTTPSPortstringOptional

HTTPS port number for secure communication with the Distribution Server, Allowed Value is 8384

hasOSDeploymentbooleanOptional

Set as false, Not supported via API. Use the web console to configure this setting

remoteInstallationDetailsJSON ObjectOptional

Auto-installation configuration specifying whether agents and Distribution Servers should be auto-installed on newly discovered computers

Show Sub-Attributes

isAgentAutoInstallbooleanOptional

Enable or disable automatic agent installation on newly discovered computers in this remote office

isDSAutoInstallbooleanOptional

Enable or disable automatic Distribution Server installation for this remote office

credentialDetailsJSON ObjectOptional

Credential configuration for auto-installation operations containing the credential identifier and UUID, to get the credential details, refer to Get Credential Details api

Show Sub-Attributes

credentialIDstringOptional

Numeric identifier of the credential to use for agent auto-installation. Use -1 to indicate no credential (Cloud products)

credentialUUIDstringOptional

UUID of the credential to use for agent auto-installation. Use '--' to indicate no credential (Cloud products)

replicationPolicyJSON ObjectOptional

Replication policy assignment containing the policy identifier for data synchronization between DS and central server

Show Sub-Attributes

replicationPolicyIDstringOptional

Identifier of the replication policy to assign to this remote office. Fetch available IDs from List Replication Policies

remoteControlSettingsJSON ObjectOptional

Remote control session settings for data compression and display color depth

Show Sub-Attributes

compressionstringOptional

Remote control data compression setting: 0 = disabled, 1 = enabled. Enabling compression reduces bandwidth usage during remote sessions

colorQualitystringOptional

Remote control display color depth in bits: 4 (16 colors), 8 (256 colors), 16 (High Color), or 24 (True Color)

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request PUT \
  --url https://appdomain/dcapi/som/remote-offices/{remote_office_id} \
  --header 'Accept: application/remoteOfficeUpdateStatus.v1+json' \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/remoteOfficeDetails.v1+json' \
  --data '{"uniqueServiceID":1776064906199,"dsDetails":{"dsHTTPSPort":"8383","dsName":"DS-NYC-01","dsIPAddress":["10.1.0.10"],"domainNetbiosName":"CORP","dsDNSName":"DS-NYC-01.corp.local"},"description":"Updated NYC branch","replicationPolicy":{"replicationPolicyID":1},"remoteOfficeName":"Branch Office NYC Updated","remoteInstallationDetails":{"credentialDetails":{"credentialUUID":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","credentialID":101},"isDSAutoInstall":false,"isAgentAutoInstall":true},"isProxyDefined":false,"agentCommunication":"HTTPS","remoteControlSettings":{"compression":"0","colorQuality":"24"},"hasDS":true,"hasOSDeployment":false}'

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/som/remote-offices/{remote_office_id}"))
        .header("Content-Type", "application/remoteOfficeDetails.v1+json")
        .header("Accept", "application/remoteOfficeUpdateStatus.v1+json")
        .header("Authorization", " d92d4xxxxxxxxxxxxx15f52")
        .method("PUT", HttpRequest.BodyPublishers.ofString("{\"uniqueServiceID\":1776064906199,\"dsDetails\":{\"dsHTTPSPort\":\"8383\",\"dsName\":\"DS-NYC-01\",\"dsIPAddress\":[\"10.1.0.10\"],\"domainNetbiosName\":\"CORP\",\"dsDNSName\":\"DS-NYC-01.corp.local\"},\"description\":\"Updated NYC branch\",\"replicationPolicy\":{\"replicationPolicyID\":1},\"remoteOfficeName\":\"Branch Office NYC Updated\",\"remoteInstallationDetails\":{\"credentialDetails\":{\"credentialUUID\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"credentialID\":101},\"isDSAutoInstall\":false,\"isAgentAutoInstall\":true},\"isProxyDefined\":false,\"agentCommunication\":\"HTTPS\",\"remoteControlSettings\":{\"compression\":\"0\",\"colorQuality\":\"24\"},\"hasDS\":true,\"hasOSDeployment\":false}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

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

payload = "{\"uniqueServiceID\":1776064906199,\"dsDetails\":{\"dsHTTPSPort\":\"8383\",\"dsName\":\"DS-NYC-01\",\"dsIPAddress\":[\"10.1.0.10\"],\"domainNetbiosName\":\"CORP\",\"dsDNSName\":\"DS-NYC-01.corp.local\"},\"description\":\"Updated NYC branch\",\"replicationPolicy\":{\"replicationPolicyID\":1},\"remoteOfficeName\":\"Branch Office NYC Updated\",\"remoteInstallationDetails\":{\"credentialDetails\":{\"credentialUUID\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"credentialID\":101},\"isDSAutoInstall\":false,\"isAgentAutoInstall\":true},\"isProxyDefined\":false,\"agentCommunication\":\"HTTPS\",\"remoteControlSettings\":{\"compression\":\"0\",\"colorQuality\":\"24\"},\"hasDS\":true,\"hasOSDeployment\":false}"

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

conn.request("PUT", "/dcapi/som/remote-offices/{remote_office_id}", payload, headers)

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

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


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

    data=Map();
    data.put("remoteOfficeID","value");
    data.put("remoteOfficeName","value");
    data.put("description","value");
    data.put("agentCommunication","value");
    data.put("uniqueServiceID","value");
    data.put("isProxyDefined",true);
    data_proxyDetails=Map();
    data_proxyDetails.put("proxyHost","value");
    data_proxyDetails.put("proxyPort","value");
    data_proxyDetails.put("proxyUsername","value");
    data_proxyDetails.put("proxyPassword","value");
    data.put("proxyDetails",data_proxyDetails);
    data.put("hasDS",true);
    data_dsDetails=Map();
    data_dsDetails.put("domainNetbiosName","value");
    data_dsDetails.put("dsName","value");
    data_dsDetails_dsIPAddress=List();
    data_dsDetails_dsIPAddress.add("value");
    data_dsDetails.put("dsIPAddress",data_dsDetails_dsIPAddress);
    data_dsDetails.put("dsDNSName","value");
    data_dsDetails.put("dsHTTPSPort","value");
    data.put("dsDetails",data_dsDetails);
    data.put("hasOSDeployment",true);
    data_remoteInstallationDetails=Map();
    data_remoteInstallationDetails.put("isAgentAutoInstall",true);
    data_remoteInstallationDetails.put("isDSAutoInstall",true);
    data_remoteInstallationDetails_credentialDetails=Map();
    data_remoteInstallationDetails_credentialDetails.put("credentialID","value");
    data_remoteInstallationDetails_credentialDetails.put("credentialUUID","value");
    data_remoteInstallationDetails.put("credentialDetails",data_remoteInstallationDetails_credentialDetails);
    data.put("remoteInstallationDetails",data_remoteInstallationDetails);
    data_replicationPolicy=Map();
    data_replicationPolicy.put("replicationPolicyID","value");
    data.put("replicationPolicy",data_replicationPolicy);
    data_remoteControlSettings=Map();
    data_remoteControlSettings.put("compression","value");
    data_remoteControlSettings.put("colorQuality","value");
    data.put("remoteControlSettings",data_remoteControlSettings);

    response = invokeUrl
    [
        url: "https://appDomain/dcapi/som/remote-offices/{remote_office_id}"
        type: PUT
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Content-Type", "application/remoteOfficeDetails.v1+json")
$headers.Add("Accept", "application/remoteOfficeUpdateStatus.v1+json")
$headers.Add("Authorization", " d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomain/dcapi/som/remote-offices/{remote_office_id}' -Method PUT -Headers $headers -ContentType 'application/remoteOfficeDetails.v1+json' -Body '{"uniqueServiceID":1776064906199,"dsDetails":{"dsHTTPSPort":"8383","dsName":"DS-NYC-01","dsIPAddress":["10.1.0.10"],"domainNetbiosName":"CORP","dsDNSName":"DS-NYC-01.corp.local"},"description":"Updated NYC branch","replicationPolicy":{"replicationPolicyID":1},"remoteOfficeName":"Branch Office NYC Updated","remoteInstallationDetails":{"credentialDetails":{"credentialUUID":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","credentialID":101},"isDSAutoInstall":false,"isAgentAutoInstall":true},"isProxyDefined":false,"agentCommunication":"HTTPS","remoteControlSettings":{"compression":"0","colorQuality":"24"},"hasDS":true,"hasOSDeployment":false}'

Sample Request Body

Update remote office with Distribution Server

Copied!

  {
    "uniqueServiceID": 1776064906199,
    "dsDetails": {
      "dsHTTPSPort": "8383",
      "dsName": "DS-NYC-01",
      "dsIPAddress": [
        "10.1.0.10"
      ],
      "domainNetbiosName": "CORP",
      "dsDNSName": "DS-NYC-01.corp.local"
    },
    "description": "Updated NYC branch",
    "replicationPolicy": {
      "replicationPolicyID": 1
    },
    "remoteOfficeName": "Branch Office NYC Updated",
    "remoteInstallationDetails": {
      "credentialDetails": {
        "credentialUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "credentialID": 101
      },
      "isDSAutoInstall": false,
      "isAgentAutoInstall": true
    },
    "isProxyDefined": false,
    "agentCommunication": "HTTPS",
    "remoteControlSettings": {
      "compression": "0",
      "colorQuality": "24"
    },
    "hasDS": true,
    "hasOSDeployment": false
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

remoteOfficeIDstring

Unique identifier of the created or updated remote office. Present only in update responses

statusboolean

true if the remote office was created or updated successfully

messagestring

Descriptive message providing details about the outcome of the remote office operation. Present on update or when an error occurs

agentMSICreationFailedboolean

true if MSI creation for agent failed during the operation

- HTTP code 400

Response Body - application/json

JSON Object

Hide Sub-Attributes

statusCodestring

HTTP status code (400)

errorCodestring

API-specific error code identifying the validation failure

messagestring

Error message describing the validation failure

- HTTP code 404

Response Body - application/json

JSON Object

Hide Sub-Attributes

statusCodestring

HTTP status code (404)

errorCodestring

Error code identifying the resource that was not found

messagestring

Error message describing the missing resource

- HTTP code 412

Response Body - application/json

JSON Object

Hide Sub-Attributes

statusCodestring

HTTP status code (412)

errorCodestring

Precondition failed error code identifying the business logic violation

messagestring

Error message describing the precondition failed while processing request

Possible Response Codes

200HTTP code

400HTTP code

404HTTP code

412HTTP code

Sample Response: HTTP 200

Remote office updated

Copied!

  {
    "remoteOfficeID": "906",
    "message": "Remote Office US DS has been modified successfully",
    "status": true
  }

▼ Show full

Sample Response: HTTP 400

Cannot update the local office

Copied!

  {
    "errorCode": "30060",
    "message": "Local office cannot be updated",
    "statusCode": 400
  }

▼ Show full

Required remote office parameters are missing

Copied!

  {
    "errorCode": "30052",
    "message": "Remote office parameters are missing",
    "statusCode": 400
  }

▼ Show full

Sample Response: HTTP 404

Remote office not found

Copied!

  {
    "errorCode": "30028",
    "message": "Remote office not found",
    "statusCode": 404
  }

▼ Show full

Replication policy not found

Copied!

  {
    "errorCode": "30027",
    "message": "Replication policy not found",
    "statusCode": 404
  }

▼ Show full

OSD PXE media not found

Copied!

  {
    "errorCode": "30079",
    "message": "OSD media not found",
    "statusCode": 404
  }

▼ Show full

Sample Response: HTTP 412

Distribution server limit reached for the license

Copied!

  {
    "errorCode": "20216",
    "message": "Distribution server limit reached",
    "statusCode": 412
  }

▼ Show full

Branch name 'Local Office' is reserved

Copied!

  {
    "errorCode": "30058",
    "message": "Local Office name is not allowed",
    "statusCode": 412
  }

▼ Show full

Remote office name already exists

Copied!

  {
    "errorCode": "30053",
    "message": "Remote office name already exists",
    "statusCode": 412
  }

▼ Show full

Distribution server already added to another office

Copied!

  {
    "errorCode": "30054",
    "message": "Distribution server is already added to another remote office",
    "statusCode": 412
  }

▼ Show full

Domain name not found for credentials

Copied!

  {
    "errorCode": "30073",
    "message": "Domain name not found for the given credentials",
    "statusCode": 412
  }

▼ Show full

Domain does not match the given credentials

Copied!

  {
    "errorCode": "30035",
    "message": "Domain does not match with the credentials provided",
    "statusCode": 412
  }

▼ Show full

Proxy not allowed when client certificate authentication is enabled

Copied!

  {
    "errorCode": "30078",
    "message": "Proxy is not allowed when client certificate authentication is enabled",
    "statusCode": 412
  }

▼ Show full

Cannot rename remote office mapped with integrated product (MSP)

Copied!

  {
    "errorCode": "30059",
    "message": "Cannot rename remote office that is mapped with other product",
    "statusCode": 412
  }

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