---
title: "Create a view"
method: POST
path: "/v1/views"
tags: ["Views"]
---

# Create a view

`POST /v1/views`

## Request

- Base URL: `https://api.folk.app`
- URL: `https://api.folk.app/v1/views`
- Auth: HTTP bearer

Create a view in a group: a table view, or a kanban view grouped by a single select field. The settings that aren't sent get the defaults of the entity type and the view type.

## Headers

- `Idempotency-Key` string: A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

## Request body

- union: A view of a group. Its settings depend on its `type`: `sort` for table views, `groupBy` and `columns` for kanban views.
  - object
    - `groupId` string, required: The group the view belongs to.
    - `name` string, required
    - `entityType` string, required: The entity type of the view: `person`, `company`, or the name of an object type of the group.
    - `filter` object, nullable: The filter of the view, `null` or absent for no filter. Unlike the search endpoints, the filter is a list of conditions.
      - `combinator` 'and' | 'or', required: The logical operator combining the conditions.
      - `conditions` object[], required: The conditions of the filter, in order, at most 50. The same field can appear in several conditions. An empty list means no filter.
        - `field` string, required: The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues.<groupId>.<Field name>`.
        - `operator` 'eq' | 'not_eq' | 'like' | 'not_like' | 'gt' | 'lt' | 'in' | 'all' | 'not_in' | 'empty' | 'not_empty', required
        - `value` union: The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users by `{ id }` or `{ email }`, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`).
          - string
          - string[]
          - union[]
            - union
              - …
    - `visibleFields` string[]: The fields shown by the view, in display order, with the same keys as the filter, at most 100. The name column is always shown and is never listed.
    - `position` union: Where the view goes among the views of its group: `{ "after": <viewId> }`, `{ "before": <viewId> }`, `{ "after": null }` for the first position or `{ "before": null }` for the last one. Last by default.
      - object
        - `after` string, nullable, required
      - object
        - `before` string, nullable, required
    - `type` 'table', required
    - `sort` object: The sort of the view. When the sorted field no longer exists, the default sort of the entity type is returned.
      - `field` string, required
      - `direction` 'asc' | 'desc', required
  - object
    - `groupId` string, required: The group the view belongs to.
    - `name` string, required
    - `entityType` string, required: The entity type of the view: `person`, `company`, or the name of an object type of the group.
    - `filter` object, nullable: The filter of the view, `null` or absent for no filter. Unlike the search endpoints, the filter is a list of conditions.
      - `combinator` 'and' | 'or', required: The logical operator combining the conditions.
      - `conditions` object[], required: The conditions of the filter, in order, at most 50. The same field can appear in several conditions. An empty list means no filter.
        - `field` string, required: The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues.<groupId>.<Field name>`.
        - `operator` 'eq' | 'not_eq' | 'like' | 'not_like' | 'gt' | 'lt' | 'in' | 'all' | 'not_in' | 'empty' | 'not_empty', required
        - `value` union: The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users by `{ id }` or `{ email }`, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`).
          - string
          - string[]
          - union[]
            - union
              - …
    - `visibleFields` string[]: The fields shown by the view, in display order, with the same keys as the filter, at most 100. The name column is always shown and is never listed.
    - `position` union: Where the view goes among the views of its group: `{ "after": <viewId> }`, `{ "before": <viewId> }`, `{ "after": null }` for the first position or `{ "before": null }` for the last one. Last by default.
      - object
        - `after` string, nullable, required
      - object
        - `before` string, nullable, required
    - `type` 'kanban', required
    - `groupBy` string, required: The single select field the columns come from.
    - `columns` object[]: The columns, in display order: every option of the `groupBy` field once, plus `null` for the "No value" column. By default, the options in their order, all visible.
      - `option` string, nullable, required: The label of the option of the `groupBy` field, `null` for the "No value" column.
      - `hidden` boolean

## Response `200`

The created view.

- object
  - `data` union, required
    - object: A view displaying the entities as rows.
      - `id` string, required
      - `groupId` string, nullable, required: The group the view belongs to, `null` for personal views, which belong to no group.
      - `name` string, required
      - `entityType` string, required: The entity type of the view: `person`, `company`, or the name of an object type of the group.
      - `filter` object, nullable, required: The filter of the view, `null` when the view has no filter. Unlike the search endpoints, the filter is a list of conditions.
        - `combinator` 'and' | 'or', required: The logical operator combining the conditions.
        - `conditions` object[], required: The conditions of the filter, in order. The same field can appear in several conditions.
          - `field` string, required: The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues.<groupId>.<Field name>`.
          - `operator` 'eq' | 'not_eq' | 'like' | 'not_like' | 'gt' | 'lt' | 'in' | 'all' | 'not_in' | 'empty' | 'not_empty', required
          - `value` union: The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`).
            - string
            - string[]
            - object[]
              - …
      - `visibleFields` string[], required: The fields shown by the view, in display order, with the same keys as the filter. The name column is always shown and never listed.
      - `position` object, required: The position of the view in the list of views of its group, or among the user's personal views, as in the app's sidebar.
        - `after` string, nullable, required: The id of the view just before this one in its group, or among the personal views, `null` for the first view.
      - `createdAt` string, date-time, required
      - `createdBy` object, nullable, required: The user who created the view, `null` when it was created by folk.
        - `id` string, required
        - `fullName` string, required
        - `email` string, required
      - `type` 'table', required
      - `sort` object, required: The sort of the view. When the sorted field no longer exists, the default sort of the entity type is returned.
        - `field` string, required
        - `direction` 'asc' | 'desc', required
    - object: A view displaying the entities as cards, in columns.
      - `id` string, required
      - `groupId` string, nullable, required: The group the view belongs to, `null` for personal views, which belong to no group.
      - `name` string, required
      - `entityType` string, required: The entity type of the view: `person`, `company`, or the name of an object type of the group.
      - `filter` object, nullable, required: The filter of the view, `null` when the view has no filter. Unlike the search endpoints, the filter is a list of conditions.
        - `combinator` 'and' | 'or', required: The logical operator combining the conditions.
        - `conditions` object[], required: The conditions of the filter, in order. The same field can appear in several conditions.
          - `field` string, required: The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues.<groupId>.<Field name>`.
          - `operator` 'eq' | 'not_eq' | 'like' | 'not_like' | 'gt' | 'lt' | 'in' | 'all' | 'not_in' | 'empty' | 'not_empty', required
          - `value` union: The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`).
            - string
            - string[]
            - object[]
              - …
      - `visibleFields` string[], required: The fields shown by the view, in display order, with the same keys as the filter. The name column is always shown and never listed.
      - `position` object, required: The position of the view in the list of views of its group, or among the user's personal views, as in the app's sidebar.
        - `after` string, nullable, required: The id of the view just before this one in its group, or among the personal views, `null` for the first view.
      - `createdAt` string, date-time, required
      - `createdBy` object, nullable, required: The user who created the view, `null` when it was created by folk.
        - `id` string, required
        - `fullName` string, required
        - `email` string, required
      - `type` 'kanban', required
      - `groupBy` string, required: The single select field the columns come from.
      - `columns` object[], required: The columns, in display order: one per option of the `groupBy` field, plus the "No value" column.
        - `option` string, nullable, required: The label of the option of the `groupBy` field, `null` for the "No value" column.
        - `hidden` boolean, required
  - `deprecations` string[]

## Other responses

- `400`: The request was unacceptable, often due to missing an invalid parameter.
- `401`: No valid API key provided.
- `403`: The API key doesn’t have permissions to perform the request.
- `404`: The requested resource doesn’t exist.
- `409`: A request with the same `Idempotency-Key` is still being processed, or the resource is in a state that does not allow the operation.
- `422`: The request was unacceptable, often due to missing or invalid parameters.
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
- `500`: Something went wrong on our end.
- `503`: The server is overloaded or down for maintenance.

## Changes

- **2026-11-03** `c6818f3ba60d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/folk/apis/folk-external-api/changes/v1/views/post.md)

---

[API](https://skmtc.dev/folk/apis/folk-external-api.md) - [All operations](https://skmtc.dev/folk/apis/folk-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/folk/apis/folk-external-api/revisions/c6818f3ba60d?raw)