Create a new remote office

Creates a new remote office (branch office). Supports configuring DS details, proxy settings, replication policy, and auto-install options.

Endpoints

post /dcapi/som/remote-offices

Copy full URL

Request URL

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

Scope

SOM.CREATECopied!

Header

Authorization: d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory

application/remoteOfficeDetails.v1+jsonCopied!

AcceptstringMandatory

application/remoteOfficeAddedStatus.v1+jsonCopied!

- 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 POST \
  --url https://appdomain/dcapi/som/remote-offices \
  --header 'Accept: application/remoteOfficeAddedStatus.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":"New York City branch","replicationPolicy":{"replicationPolicyID":1},"remoteOfficeName":"Branch Office NYC","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"))
        .header("Content-Type", "application/remoteOfficeDetails.v1+json")
        .header("Accept", "application/remoteOfficeAddedStatus.v1+json")
        .header("Authorization", " d92d4xxxxxxxxxxxxx15f52")
        .method("POST", 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\":\"New York City branch\",\"replicationPolicy\":{\"replicationPolicyID\":1},\"remoteOfficeName\":\"Branch Office NYC\",\"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\":\"New York City branch\",\"replicationPolicy\":{\"replicationPolicyID\":1},\"remoteOfficeName\":\"Branch Office NYC\",\"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/remoteOfficeAddedStatus.v1+json",
    'Authorization': " d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("POST", "/dcapi/som/remote-offices", 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/remoteOfficeAddedStatus.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"
        type: POST
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Content-Type", "application/remoteOfficeDetails.v1+json")
$headers.Add("Accept", "application/remoteOfficeAddedStatus.v1+json")
$headers.Add("Authorization", " d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomain/dcapi/som/remote-offices' -Method POST -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":"New York City branch","replicationPolicy":{"replicationPolicyID":1},"remoteOfficeName":"Branch Office NYC","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

Create 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": "New York City branch",
    "replicationPolicy": {
      "replicationPolicyID": 1
    },
    "remoteOfficeName": "Branch Office NYC",
    "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 created

Copied!

  {
    "status": true
  }

▼ Show full

Sample Response: HTTP 400

Required remote office parameters are missing

Copied!

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

▼ Show full

Sample Response: HTTP 404

Replication policy does not exist

Copied!

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

▼ Show full

Sample Response: HTTP 412

Remote office name already exists

Copied!

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

▼ Show full

DS limit reached or incompatible license

Copied!

  {
    "errorCode": "20216",
    "message": "Distribution Server limit reached or incompatible license",
    "statusCode": 412
  }

▼ Show full

Cannot use Local Office as remote office name

Copied!

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

▼ Show full

DS is already added under another remote office

Copied!

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

▼ Show full

Domain NetBiosName does not match with the credentials

Copied!

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

▼ Show full

Domain not found for the given credentials

Copied!

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

▼ Show full

Proxy not allowed when client certificate auth is enabled

Copied!

  {
    "errorCode": "30078",
    "message": "Proxy is not allowed when client certificate authentication is enabled",
    "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.