# Create a new remote office

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

## Endpoint

`POST /dcapi/som/remote-offices`

## Request

### Request URL

`https://`[*{serverurl}*](https://www.manageengine.com/products/desktop-central/help/api/cloud/oauth-authentication-endpoint-domain.html)`/dcapi/som/remote-offices`

### Scope

`DesktopCentralCloud.SOM.CREATE`

### Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

- **Content-Type** `string` **Mandatory**: `application/remoteOfficeDetails.v1+json`
- **Accept** `string` **Mandatory**: `application/remoteOfficeAddedStatus.v1+json`

#### Request Body

`application/json`

- `JSON Object`
  - **remoteOfficeID** `string` *Optional*: Specifies the unique identifier of the remote office. Required only during remote office update, should not be provided during creation.
  - **remoteOfficeName** `string` *Optional*: Administrator-defined display name for the remote office
  - **description** `string` *Optional*: Optional administrator-provided description for the remote office (max 250 characters)
  - **agentCommunication** `string` *Optional*: Protocol for agent-to-server communication. Allowed value: `'HTTPS'`
  - **uniqueServiceID** `string` *Optional*: 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](https://www.manageengine.com/products/desktop-central/help/api/cloud/remote-offices-load-remote-office-computers.html)
  - **isProxyDefined** `boolean` *Optional*: Set to true to configure a proxy server for agent communication in this remote office. When true, the proxyDetails object is required
  - **proxyDetails** `JSON Object` *Optional*: Proxy server configuration including host, port, and credentials, These details required only when isProxyDefined is set to true
  - **hasDS** `boolean` *Optional*: Set to true to associate a Distribution Server with this remote office. When true, the dsDetails object is required
  - **dsDetails** `JSON Object` *Optional*: Distribution server details including hostname, domain, IP, and port, These details required only when hasDS is set to true
  - **hasOSDeployment** `boolean` *Optional*: Set to false, Not supported via API. Use the web console to configure this setting
  - **remoteInstallationDetails** `JSON Object` *Optional*: Auto-install configuration including agent and DS auto-install settings
  - **replicationPolicy** `JSON Object` *Optional*: Replication policy assignment with policy ID
  - **remoteControlSettings** `JSON Object` *Optional*: Remote control settings for compression and color quality. Only compression=1 and colorQuality=16 applicable for Cloud

### Sample Request

```curl
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 '{}'
```

### Sample Request Body

#### Create remote office with Distribution Server

```json
{
  "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
}
```

#### Create remote office with DS, proxy, and OS deployment

```json
{
  "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"
  }
}
```

## Response Parameters

### HTTP Code 200

Response Body: `application/json`

- `JSON Object`
  - **remoteOfficeID** `string`: Unique identifier of the created or updated remote office. Present only in update responses
  - **status** `boolean`: true if the remote office was created or updated successfully
  - **message** `string`: Descriptive message providing details about the outcome of the remote office operation. Present on update or when an error occurs
  - **agentMSICreationFailed** `boolean`: true if MSI creation for agent failed during the operation

### HTTP Code 400

Response Body: `application/json`

- `JSON Object`
  - **statusCode** `string`: HTTP status code (400)
  - **errorCode** `string`: API-specific error code identifying the validation failure
  - **message** `string`: Error message describing the validation failure

### HTTP Code 404

Response Body: `application/json`

- `JSON Object`
  - **statusCode** `string`: HTTP status code (404)
  - **errorCode** `string`: Error code identifying the resource that was not found
  - **message** `string`: Error message describing the missing resource

### HTTP Code 412

Response Body: `application/json`

- `JSON Object`
  - **statusCode** `string`: HTTP status code (412)
  - **errorCode** `string`: Precondition failed error code identifying the business logic violation
  - **message** `string`: Error message describing the precondition failed while processing request

### Possible Response Codes

- **200**: HTTP code
- **400**: HTTP code
- **404**: HTTP code
- **412**: HTTP code

### Sample Response: HTTP 200

#### Remote office created

```json
{
  "status": true
}
```

### Sample Response: HTTP 400

#### Required remote office parameters are missing

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

### Sample Response: HTTP 404

#### Replication policy does not exist

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

### Sample Response: HTTP 412

#### Remote office name already exists

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

#### DS limit reached or incompatible license

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

#### Cannot use Local Office as remote office name

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

#### DS is already added under another remote office

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

#### Domain NetBiosName does not match with the credentials

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

#### Domain not found for the given credentials

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

#### Proxy not allowed when client certificate auth is enabled

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

![ ](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

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