# 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 URL

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

## Scope

`SOM.CREATE`

## Header

`Authorization: d92d4xxxxxxxxxxxxx15f52`

## Request Parameters

### Request Headers

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

### Request Body

`application/json`

- `remoteOfficeID` `string` — Optional  
  Specifies the unique identifier of the remote office. Required only for update operations; not applicable for create operations.

- `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 values: `HTTPS`.

- `uniqueServiceID` `string` — Optional  
  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](https://www.manageengine.com/products/desktop-central/help/api/onpremise/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 hostname, port, and authentication credentials.

- `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 configuration including hostname, domain, IP addresses, and communication port.

- `hasOSDeployment` `boolean` — Optional  
  Set as false. Not supported via API. Use the web console to configure this setting.

- `remoteInstallationDetails` `JSON Object` — Optional  
  Auto-installation configuration specifying whether agents and Distribution Servers should be auto-installed on newly discovered computers.

- `replicationPolicy` `JSON Object` — Optional  
  Replication policy assignment containing the policy identifier for data synchronization between DS and central server.

- `remoteControlSettings` `JSON Object` — Optional  
  Remote control session settings for data compression and display color depth.

## Sample Request

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

## 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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "credentialID": 101
    },
    "isDSAutoInstall": false,
    "isAgentAutoInstall": true
  },
  "isProxyDefined": false,
  "agentCommunication": "HTTPS",
  "remoteControlSettings": {
    "compression": "0",
    "colorQuality": "24"
  },
  "hasDS": true,
  "hasOSDeployment": false
}
```

## Response Parameters

### HTTP Code 200

Response Body — `application/json`

- `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`

- `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`

- `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`

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