> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Views

A view is a saved way of looking at the entities of a [group](https://developer.folk.app/core-concepts/groups.md): which ones are shown, in which order, and with which fields. A group has several views, listed in the sidebar of the folk app, and every member of the group sees the same views.

You can [list](https://developer.folk.app/api-reference/views/list-views.md), [get](https://developer.folk.app/api-reference/views/get-a-view.md), [create](https://developer.folk.app/api-reference/views/create-a-view.md), [update](https://developer.folk.app/api-reference/views/update-a-view.md) and [delete](https://developer.folk.app/api-reference/views/delete-a-view.md) views through the API, and list, get, create and update them through the [MCP](https://developer.folk.app/mcp/tools.md#views). A view created through the API shows up in the app, and a view created in the app can be read back through the API.

Reading the views of a group requires access to the group. Creating, updating or deleting them requires the `contributor` or `admin` role on the group: a `reader` gets a `403`.

## Entity type and view type

Each view shows one **entity type**, given by `entityType`:

* `person`: the people of the group;
* `company`: the companies of the group;
* the name of an object type of the group, such as `Deals`: the objects of that type. See [Custom objects](https://developer.folk.app/core-concepts/custom-objects.md).

Each view has a **view type**, given by `type`:

* `table`: the entities as rows, sorted by `sort`;
* `kanban`: the entities as cards, in columns made from the options of a single select field, given by `groupBy`.

The group, the entity type and the view type of a view never change. To change them, create a new view.

```json Table view theme={null}
{
  "id": "viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71",
  "groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
  "name": "Hot leads",
  "entityType": "person",
  "type": "table",
  "filter": {
    "combinator": "and",
    "conditions": [
      {
        "field": "interactionMetadata.workspace.lastInteractedAt",
        "operator": "gt",
        "value": "30-days-ago"
      }
    ]
  },
  "visibleFields": ["jobTitle", "companies", "emails"],
  "sort": {
    "field": "interactionMetadata.user.lastInteractedAt",
    "direction": "desc"
  },
  "position": { "after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71" },
  "createdAt": "2025-07-17T09:00:00.000Z",
  "createdBy": {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "john.doe@example.com"
  }
}
```

## Settings

### Filter

`filter` selects the entities the view shows. It combines a list of conditions with `and` or `or`:

```json theme={null}
{
  "combinator": "and",
  "conditions": [
    { "field": "jobTitle", "operator": "like", "value": "engineer" },
    { "field": "customFieldValues.grp_92ab3f1c-0386-434d-82d7-a91eb6badd71.Status", "operator": "in", "value": ["Active"] }
  ]
}
```

Conditions use the field keys, operators and value formats of the [search filters](https://developer.folk.app/api-reference/filtering.md), with a few differences:

* the conditions are a list, so the same field can appear in several conditions;
* `in`, `not_in` and `all` always take a list, even for a single value;
* `eq` and `not_eq` on select, user and reference fields take a list and mean "exactly this set of values";
* `empty` and `not_empty` take no `value`.

Select options are given by label, users by `{ "id" }` or `{ "email" }`, people, companies, objects and groups by `{ "id" }`. Dates are given as `YYYY-MM-DD` or as relative dates, such as `today` or `7-days-ago`. See [Dates](https://developer.folk.app/api-reference/filtering.md#dates).

A view only accepts the fields and operators the app offers for its entity type: anything else is rejected with a `422`.

### Sort

`sort` orders the entities of a table view, by a single field: `{ "field": "name", "direction": "asc" }`. Kanban views have no sort.

### Visible fields

`visibleFields` is the ordered list of the fields shown: the columns of a table view, or the fields on the cards of a kanban view. The name of the entities is always shown, so it is never listed.

### Kanban

`groupBy` is the key of a single select field of the view's entity type, such as `customFieldValues.grp_92ab3f1c-0386-434d-82d7-a91eb6badd71.Stage`. Each option of the field makes a column. If the group has no single select field for the entity type, [create one](https://developer.folk.app/api-reference/group-custom-fields/create-a-group-custom-field.md) first. Creating a field requires the `admin` role on the group.

`columns` lists every option of the `groupBy` field once, plus `null` for the "No value" column, in display order, each with `hidden`:

```json theme={null}
[
  { "option": "Lead", "hidden": false },
  { "option": "Qualified", "hidden": false },
  { "option": "Lost", "hidden": true },
  { "option": null, "hidden": false }
]
```

### Position

`position` places the view among the views of its group, as in the app's sidebar. A view always returns `{ "after": <id of the previous view> }`, or `{ "after": null }` when it is the first one. To move a view, send `{ "after": <viewId> }` or `{ "before": <viewId> }`, with a view of the same group, or `{ "after": null }` to put it first and `{ "before": null }` to put it last.

## Creating and updating a view

A view is created with a `groupId`, a `name`, an `entityType` and a `type`, plus `groupBy` for a kanban view. Every other setting is optional.

An update changes only the settings it sends. `filter`, `visibleFields`, `sort` and `columns` replace the current value as a whole: to add a condition, send back every current condition with the new one. The settings returned when you get a view can be sent back as they are.

A group keeps at least one view of each entity type: deleting the last one is rejected with a `422`.

## Defaults

The settings that aren't sent at creation get defaults. They depend only on the entity type and the view type, not on the other views of the group:

| Setting | Default |
| - | - |
| `filter` | No condition: the view shows every entity of the group. |
| `sort` | People: `interactionMetadata.user.lastInteractedAt` descending, your last interaction first. Companies: `name` ascending. Objects: `createdAt` descending. |
| `visibleFields` | Table views: the default columns of the app for the entity type, then every custom field of the entity type. Kanban views: `companies`, `jobTitle`, `emails` and `interactionMetadata.user.lastInteractedAt` on people cards, no field on company cards, every field on object cards. |
| `columns` | Every option of the `groupBy` field in its order, then "No value", all visible. |
| `position` | Last in the group. |

## When a field is deleted

Deleting a custom field of the group changes the views that use it:

* conditions on the field are removed from the filter;
* the field is removed from the visible fields;
* a sort on the field falls back to the default sort of the entity type.

A single select field used as the `groupBy` of a kanban view can't be deleted. Delete the kanban view, or change its `groupBy`, first.

## Fields of a view

The filter, the sort and the visible fields of a view use the same field keys. Not every field can be used in all three. The tables below list the native fields and where they can be used.

### People views

| Field | Filter | Sort | Visible field |
| - | - | - | - |
| `companies` | ✓ | ✓ | ✓ |
| `jobTitle` | ✓ | ✓ | ✓ |
| `emails` | ✓ | ✓ | ✓ |
| `interactionMetadata.user.lastInteractedAt` | — | ✓ | ✓ |
| `interactionMetadata.workspace.lastInteractedAt` | ✓ | ✓ | ✓ |
| `interactionMetadata.workspace.lastInteractedBy` | — | ✓ | ✓ |
| `urls` | ✓ | ✓ | ✓ |
| `description` | ✓ | ✓ | ✓ |
| `interactionMetadata.user.approximateCount` | — | ✓ | ✓ |
| `strongestConnection` | ✓ | ✓ | ✓ |
| `phones` | ✓ | ✓ | ✓ |
| `addresses` | ✓ | ✓ | ✓ |
| `firstName` | ✓ | ✓ | ✓ |
| `lastName` | ✓ | ✓ | ✓ |
| `birthday` | ✓ | ✓ | ✓ |
| `gender` | ✓ | ✓ | ✓ |
| `groups` | ✓ | — | ✓ |
| `createdAt` | ✓ | ✓ | ✓ |
| `createdBy` | ✓ | ✓ | ✓ |
| `addedToGroupAt` | ✓ | ✓ | ✓ |
| `addedToGroupBy` | ✓ | ✓ | ✓ |
| `fullName` | — | ✓ | — |

### Fields of the company of people

| Field | Filter | Sort | Visible field |
| - | - | - | - |
| `company.emails` | ✓ | ✓ | ✓ |
| `company.urls` | ✓ | ✓ | ✓ |
| `company.phones` | ✓ | ✓ | ✓ |
| `company.addresses` | ✓ | ✓ | ✓ |
| `company.fundingRaised` | ✓ | ✓ | ✓ |
| `company.lastFundingDate` | ✓ | ✓ | ✓ |
| `company.foundationYear` | ✓ | ✓ | ✓ |
| `company.employeeRange` | ✓ | — | ✓ |
| `company.industry` | ✓ | ✓ | ✓ |

### Company views

| Field | Filter | Sort | Visible field |
| - | - | - | - |
| `people` | — | — | ✓ |
| `urls` | ✓ | ✓ | ✓ |
| `phones` | ✓ | ✓ | ✓ |
| `emails` | ✓ | ✓ | ✓ |
| `addresses` | ✓ | ✓ | ✓ |
| `description` | ✓ | ✓ | ✓ |
| `fundingRaised` | ✓ | ✓ | ✓ |
| `lastFundingDate` | ✓ | ✓ | ✓ |
| `foundationYear` | ✓ | ✓ | ✓ |
| `employeeRange` | ✓ | — | ✓ |
| `industry` | ✓ | ✓ | ✓ |
| `groups` | ✓ | — | ✓ |
| `createdAt` | ✓ | ✓ | ✓ |
| `createdBy` | ✓ | ✓ | ✓ |
| `addedToGroupAt` | ✓ | ✓ | ✓ |
| `addedToGroupBy` | ✓ | ✓ | ✓ |
| `name` | ✓ | ✓ | — |
| `strongestConnection` | ✓ | ✓ | — |

### Object views

| Field | Filter | Sort | Visible field |
| - | - | - | - |
| `people` | ✓ | — | ✓ |
| `companies` | ✓ | ✓ | ✓ |
| `createdAt` | ✓ | ✓ | ✓ |
| `createdBy` | ✓ | ✓ | ✓ |
| `name` | ✓ | ✓ | — |

The custom fields of the group of the view are identified by their name: `customFieldValues.<groupId>.<Field name>` on people and company views, where `<groupId>` is the ID of the group, and `customFieldValues.<Field name>` on object views.

> [card] [Filtering](https://developer.folk.app/api-reference/filtering.md)
>
> Read more about operators and value formats&#x20;


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.