# Update a custom view

Source: https://api-docs.magicdoor.com/api-reference/custom-views/update-custom-view

Replaces a saved column layout in full. Renaming the view regenerates its key, so the URL you used to update it may no longer address it afterwards. Requires the `settings:write` permission.

`PUT https://services.magicdoor.com/settings/company-portal/settings/custom-views/{type}/{key}`

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

## Path parameters

- `type` (enum<string>, required) — Which list screen the view belongs to. Matched case-insensitively, and echoed back in `viewType` exactly as spelled here. One of: `Units`, `Properties`, `Leases`, `LeasesWithBalanceDue`, `DraftLeases`, `ExpiringLeases`, `PastLeases`, `LeasesWithMoveOutRequests`, `LeaseRentalApplications`, `PropertyApplications`, `AccountingBills`, `MaintenanceRequests`, `WorkOrders`, `WorkOrderBills`, `PropertyManagers`, `Owners`, `Tenants`. Example: `Leases`.
- `key` (string, required) — The view's key — its name lowercased with every run of non-alphanumeric characters turned into a hyphen. A view's key changes when its name changes. Example: `delinquent-leases`.

## Body

Content type: `application/json`

- `name` (string, required) — What to call the view. Between 3 and 50 characters, and it cannot be `Default` in any casing — that name is reserved for the built-in view. The key is regenerated from this name.
- `favorite` (boolean) — Make this the view the screen opens with. Setting it clears the flag on every other view of the same type. Default: `false`.
- `description` (string) — Free text about the view.
- `columns` (object[], required) — The columns the view shows. May be empty. When it is not empty every entry must have `selected` set to `true` and a `displayOrder`, and those orders must be the whole numbers 1 to N with no gaps and no repeats.
  - `key` (string, required) — Identifies the column. For a custom-field column, use the custom field's id.
  - `type` (enum<string>, required) — Whether this is a built-in column or one backed by a company custom field. Matched case-insensitively. One of: `System`, `Custom`.
  - `selected` (boolean) — Whether the column is shown. Default: `true`.
  - `displayOrder` (integer) — Where the column sits, counting from 1 left to right.
  - `width` (integer) — The column's width in pixels. Leave it out to let the screen decide.
  - `customFieldId` (string) — The company custom field behind this column, as a decimal string. Only meaningful on `Custom` columns.
  - `description` (string) — The column's label.

```json
{
  "name": "Delinquent leases",
  "favorite": true,
  "description": "Leases carrying a balance, worst first.",
  "columns": [
    {
      "key": "tenant",
      "type": "System",
      "selected": true,
      "displayOrder": 1,
      "width": 240
    },
    {
      "key": "balance",
      "type": "System",
      "selected": true,
      "displayOrder": 2
    },
    {
      "key": "1846551029384118272",
      "type": "Custom",
      "selected": true,
      "displayOrder": 3,
      "customFieldId": "1846551029384118272",
      "description": "Collections stage"
    }
  ]
}
```

## Example request

```bash
curl --request PUT \
  --url 'https://services.magicdoor.com/settings/company-portal/settings/custom-views/Leases/delinquent-leases' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Delinquent leases",
  "favorite": true,
  "description": "Leases carrying a balance, worst first.",
  "columns": [
    {
      "key": "tenant",
      "type": "System",
      "selected": true,
      "displayOrder": 1,
      "width": 240
    },
    {
      "key": "balance",
      "type": "System",
      "selected": true,
      "displayOrder": 2
    },
    {
      "key": "1846551029384118272",
      "type": "Custom",
      "selected": true,
      "displayOrder": 3,
      "customFieldId": "1846551029384118272",
      "description": "Collections stage"
    }
  ]
}'
```

## Responses

### 200 — The updated view, carrying its current key.

- `id` (string, required) — The view's Snowflake id, as a decimal string. The built-in default view returns the literal string `default` instead.
- `key` (string, required) — The view's key, derived from its name and used to address it in the other endpoints.
- `name` (string, required) — What the view is called on screen.
- `viewType` (enum<string>, required) — The list screen this view belongs to, capitalised. One of: `Units`, `Properties`, `Leases`, `LeasesWithBalanceDue`, `DraftLeases`, `ExpiringLeases`, `PastLeases`, `LeasesWithMoveOutRequests`, `LeaseRentalApplications`, `PropertyApplications`, `AccountingBills`, `MaintenanceRequests`, `WorkOrders`, `WorkOrderBills`, `PropertyManagers`, `Owners`, `Tenants`.
- `favorite` (boolean, required) — Whether this is the view the screen opens with. At most one view per type can be the favorite.
- `description` (string) — Free text the property manager wrote about the view. Absent when none was given.
- `columns` (object[], required) — The view's columns.
  - `key` (string, required) — Identifies the column. For a custom-field column this is the custom field's id.
  - `type` (enum<string>, required) — Whether the column is one of MagicDoor's built-in columns or one backed by a company custom field. One of: `System`, `Custom`.
  - `selected` (boolean, required) — Whether the column is shown.
  - `displayOrder` (integer) — Where the column sits, counting from 1 left to right. Absent on columns that are offered but not shown.
  - `width` (integer) — The column's width in pixels. Absent when the screen decides.
  - `customFieldId` (string) — The company custom field behind this column. Present only on `Custom` columns.
  - `description` (string) — The column's label. Absent on built-in columns, where the screen supplies the label.

```json
{
  "id": "1851203948572119040",
  "key": "delinquent-leases",
  "name": "Delinquent leases",
  "viewType": "Leases",
  "favorite": true,
  "description": "Leases carrying a balance, worst first.",
  "columns": [
    {
      "key": "tenant",
      "type": "System",
      "selected": true,
      "displayOrder": 1,
      "width": 240
    },
    {
      "key": "balance",
      "type": "System",
      "selected": true,
      "displayOrder": 2
    },
    {
      "key": "1846551029384118272",
      "type": "Custom",
      "selected": true,
      "displayOrder": 3,
      "customFieldId": "1846551029384118272",
      "description": "Collections stage"
    }
  ]
}
```

### 400 — The name is missing, shorter than 3 or longer than 50 characters, or is `Default`; or the columns are not all selected, not all numbered, or not numbered 1 to N without gaps or repeats.

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

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

### 404 — The company has no saved view with that key for that type.

### 409 — The new name produces a key another view of the same type already uses.

> **Warning:**
>
> The body replaces the view outright — columns you leave out are dropped. Read the `key` on the response and use that from then on.