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://{serverurl}/dcapi/som/remote-offices

Scope

DesktopCentralCloud.SOM.CREATECopied!

Header

Authorization: Zoho-oauthtoken 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 during remote office update, should not be provided during creation.

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 value:'HTTPS'

uniqueServiceIDstringOptional

Tracking identifier for the computer modification operation. When creating a remote office, 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 host, port, and credentials, These details required only when isProxyDefined is set to true

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 details including hostname, domain, IP, and port, These details required only when hasDS is set to true

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 to false, Not supported via API. Use the web console to configure this setting

remoteInstallationDetailsJSON ObjectOptional

Auto-install configuration including agent and DS auto-install settings

Show Sub-Attributes

isAgentAutoInstallbooleanOptional

Enable or disable automatic agent installation for discovered computers. For Cloud it is not applicable, so this must be set to false

isDSAutoInstallbooleanOptional

Enable or disable automatic Distribution Server installation.For Cloud it is not applicable, so this must be set to false

credentialDetailsJSON ObjectOptional

Credential configuration for auto-installation containing the credential identifier and UUID

Show Sub-Attributes

credentialIDstringOptional

Numeric identifier of the credential to use for auto-installation. For Cloud it is not applicable, so this must be set to -1 (no credential)

credentialUUIDstringOptional

UUID of the credential to use for auto-installation. For Cloud it is not applicable, so this must be set to '--' (no credential)

replicationPolicyJSON ObjectOptional

Replication policy assignment with policy ID

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 settings for compression and color quality. Only compression=1 and colorQuality=16 applicable for Cloud

Show Sub-Attributes

compressionstringOptional

Remote control data compression setting: 0 = Fast, 1 = Best. For Cloud it is not applicable, so this must be set to 1

colorQualitystringOptional

Remote control display color depth in bits: 4, 8, 16, or 24. For Cloud it is not applicable, so this must be set to 16

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request POST \
  --url https://appdomains/dcapi/som/remote-offices \
  --header 'Accept: application/remoteOfficeAddedStatus.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/remoteOfficeDetails.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/som/remote-offices"))
        .header("Content-Type", "application/remoteOfficeDetails.v1+json")
        .header("Accept", "application/remoteOfficeAddedStatus.v1+json")
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("POST", 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/remoteOfficeDetails.v1+json",
    'Accept': "application/remoteOfficeAddedStatus.v1+json",
    'Authorization': "Zoho-oauthtoken  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();

    response = invokeUrl
    [
        url: "https://appDomains/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", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomains/dcapi/som/remote-offices' -Method POST -Headers $headers -ContentType 'application/remoteOfficeDetails.v1+json' -Body '{}'

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": "--",
        "credentialID": "-1"
      },
      "isDSAutoInstall": false,
      "isAgentAutoInstall": false
    },
    "isProxyDefined": false,
    "agentCommunication": "HTTPS",
    "remoteControlSettings": {
      "compression": "1",
      "colorQuality": "16"
    },
    "hasDS": true,
    "hasOSDeployment": false
  }

▼ Show full

Create remote office with DS, proxy, and OS deployment

Copied!

  {
    "uniqueServiceID": 1776064906199,
    "dsDetails": {
      "dsHTTPSPort": "8384",
      "dsName": "US",
      "dsIPAddress": [
        "10.92.32.36"
      ],
      "domainNetbiosName": "WORKGROUP",
      "dsDNSName": "us.WORKGROUP.com"
    },
    "replicationPolicy": {
      "replicationPolicyID": "33469000000436006"
    },
    "remoteOfficeName": "dsfsdfsdf",
    "remoteInstallationDetails": {
      "credentialDetails": {
        "credentialUUID": "--",
        "credentialID": "-1"
      },
      "isDSAutoInstall": false,
      "isAgentAutoInstall": false
    },
    "isProxyDefined": true,
    "agentCommunication": "HTTPS",
    "remoteControlSettings": {
      "compression": 1,
      "colorQuality": 24
    },
    "hasDS": true,
    "hasOSDeployment": false,
    "proxyDetails": {
      "proxyPort": 80,
      "proxyUsername": "Proxy",
      "proxyPassword": "Proxy@123",
      "proxyHost": "US-PROXY"
    }
  }

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