# List custom views

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

Returns the company's saved column layouts for one list screen, with MagicDoor's built-in default view appended last. Requires the `settings:read` permission.

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

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

## Example request

```bash
curl --request GET \
  --url 'https://services.magicdoor.com/settings/company-portal/settings/custom-views/Leases' \
  --header 'Authorization: Bearer <token>'
```

## Responses

### 200 — The company's saved views, then the built-in default view.

- `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"
      }
    ]
  },
  {
    "id": "default",
    "key": "default",
    "name": "Default",
    "viewType": "Leases",
    "favorite": false,
    "columns": [
      {
        "key": "tenant",
        "type": "System",
        "selected": true,
        "displayOrder": 1
      },
      {
        "key": "balance",
        "type": "System",
        "selected": true,
        "displayOrder": 2
      },
      {
        "key": "1846551029384118272",
        "type": "Custom",
        "selected": false,
        "customFieldId": "1846551029384118272",
        "description": "Collections stage"
      }
    ]
  }
]
```

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

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

The built-in default view is not stored anywhere — it is assembled for each request, always comes last, and has `id` and `key` both set to `default`. It cannot be fetched, updated or deleted through the other endpoints in this section.

For screens that support company custom fields, the default view also lists each active, listable custom field as an unselected `Custom` column, so a UI can offer them without a second call. If that lookup fails the plain built-in view is returned instead.