# Set setting overrides

Source: https://api-docs.magicdoor.com/api-reference/settings/set-setting-overrides

Writes the same value as an override on one or more portfolios, properties, units or leases, creating rows that did not exist and replacing those that did. The company-level value is untouched. Requires the `settings:write` permission.

`POST https://services.magicdoor.com/settings/company-portal/settings/{settingsType}`

**Authentication:** bearer token in the `Authorization` header, as `Bearer <token>`.

## Path parameters

- `settingsType` (enum<string>, required) — Which family of settings to act on. Matched case-insensitively against the registered settings types. One of: `achpaymentprocessing`, `agentschat`, `associationviolation`, `autopayincentives`, `chat`, `chatai`, `chatailease`, `chataileaserenewal`, `chataileaserentersinsurance`, `chataimaintenancerequests`, `chataitranslation`, `communications`, `company`, `contribution`, `depositpayment`, `distribution`, `email`, `emailnotification`, `latefees`, `leasechartofaccount`, `leaseinvoice`, `leaserenewal`, `leaserentersinsurance`, `maintenancerequest`, `maintenancerequestrunbook`, `managementfee`, `outgoingpayments`, `property`, `rentalapplication`, `rentalapplicationbilling`, `rentalapplicationchartofaccount`, `rentalapplicationgeneral`, `rentalapplicationpayment`, `rentalapplicationpaymentaccount`, `rentalapplicationquestionnaire`, `rentalapplicationscreening`, `rentpayment`, `rentpaymentfailurefee`, `rentpaymentnotification`, `rentpaymentprocessingfees`, `syndication`, `tenantautopayfailednotification`, `tenantpaymentreminder`, `text`, `workorder`. Example: `property`.

## Body

Content type: `application/json`

- `settings` (object, required) — The complete settings object for the chosen `settingsType`. Every property of that type must be supplied — this is a whole-object replacement, not a patch, and anything left out falls back to the type's built-in default. Snowflake ids inside the object are sent as decimal strings.
- `targets` (object[], required) — The entities to write the override against. At least one is required.
  - `level` (enum<string>, required) — The kind of entity to override. One of: `company`, `portfolio`, `property`, `unit`, `lease`.
  - `levelId` (string, required) — The id of the entity to override, as a decimal string.

```json
{
  "settings": {
    "reserve": 500,
    "ownerApprovalLimit": 1000,
    "vendorApprovalLimit": 250
  },
  "targets": [
    {
      "level": "property",
      "levelId": "1842918365109710848"
    },
    {
      "level": "unit",
      "levelId": "1844770193882251264"
    }
  ]
}
```

## Example request

```bash
curl --request POST \
  --url 'https://services.magicdoor.com/settings/company-portal/settings/property' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "settings": {
    "reserve": 500,
    "ownerApprovalLimit": 1000,
    "vendorApprovalLimit": 250
  },
  "targets": [
    {
      "level": "property",
      "levelId": "1842918365109710848"
    },
    {
      "level": "unit",
      "levelId": "1844770193882251264"
    }
  ]
}'
```

## Responses

### 200 — The rows that were written, one per target.

- `…settings properties` (object) — Each array element carries the properties of the chosen settings type at its top level, alongside the three fields below.
- `level` (enum<string>) — The kind of entity this stored row is attached to. One of: `company`, `portfolio`, `property`, `unit`, `lease`.
- `levelId` (string) — The id of the entity this stored row is attached to. At company level this is the company's own id.
- `groupId` (string) — Identifies rows written together by a single multi-target override call. Absent on rows written on their own.

```json
[
  {
    "reserve": 500,
    "ownerApprovalLimit": 1000,
    "vendorApprovalLimit": 250,
    "level": "property",
    "levelId": "1842918365109710848",
    "groupId": "9f3c1a72-5f18-4b6d-9f0a-2c3d4e5f6a7b"
  },
  {
    "reserve": 500,
    "ownerApprovalLimit": 1000,
    "vendorApprovalLimit": 250,
    "level": "unit",
    "levelId": "1844770193882251264",
    "groupId": "9f3c1a72-5f18-4b6d-9f0a-2c3d4e5f6a7b"
  }
]
```

### 400 — The body could not be read as the chosen settings type, `targets` is empty, a settings type with its own validator rejected the values, or a target portfolio, property or unit is inactive.

### 401 — The access token is missing, expired, or invalid.

### 403 — The caller does not hold the `settings:write` permission.

### 404 — No settings type is registered under the `settingsType` in the URL, or one of the targets does not exist.

### 422 — This settings type only exists at company level and does not accept overrides.

```json
{
  "type": "https://httpstatuses.com/422",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "CompanySettings is a global-only setting and does not support overrides. Use SetCompany instead.",
  "instance": "/company-portal/settings/company",
  "traceId": "0HN7GK9C2M4PQ",
  "entityType": "CompanySetting",
  "entityId": "0"
}
```

Every target is checked before anything is written: portfolios, properties and units must exist and be active, and leases must exist. Send more than one target and the resulting rows share a `groupId`, which lets you take them all away again with [Remove an override group](https://api-docs.magicdoor.com/api-reference/settings/remove-setting-group.md).

## Settings types that cannot be overridden

These settings types exist once per company and reject this call with a `422`. Set them with [Set a company setting](https://api-docs.magicdoor.com/api-reference/settings/set-company-setting.md) instead.

- `chat`
- `chataileaserentersinsurance`
- `communications`
- `company`
- `contribution`
- `distribution`
- `email`
- `emailnotification`
- `outgoingpayments`
- `rentalapplication`
- `rentalapplicationbilling`
- `rentalapplicationchartofaccount`
- `rentalapplicationgeneral`
- `rentalapplicationpayment`
- `rentalapplicationpaymentaccount`
- `rentalapplicationquestionnaire`
- `rentalapplicationscreening`
- `text`