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

# Create a table view

`POST /api/v1/table-views`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/table-views`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recruitwithatlas/apis/atlas-api/docs/api/v1/table-views/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a view owned by your API key's user. `visibility` defaults to `private` and `isCollaborative` to `false`. `filters` and `columns` are page-defined: Atlas stores them as given and does not validate them, so a view built from invented keys will load empty in the app. Read an existing view of the same `pageType` first and copy its shape.

## Request body

- object
  - `name` string, required: View name
  - `pageType` 'people' | 'companyContacts' | 'companies', required: Page the view belongs to
  - `filters` object: Saved filter state. Opaque JSON whose shape is defined by the page, not validated here — copy it from an existing view of the same `pageType`
  - `columns` object: Defaults to an empty layout when omitted
    - `visibility` object, required: Column ID → shown
    - `order` string[], required: Column IDs, left to right
  - `sorting` object[]: Defaults to no sort when omitted
    - `id` string, required: Column ID to sort on
    - `direction` 'asc' | 'desc', required: Sort direction
  - `visibility` 'public' | 'team' | 'private': Defaults to `private` when omitted
  - `isCollaborative` boolean: Whether other users who can see a shared view may change it. Defaults to `false` when omitted

## Response `201`

Table view created

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, uuid, required: Table view ID
    - `name` string, required: View name
    - `pageType` 'people' | 'companyContacts' | 'companies', required: Page the view belongs to
    - `filters` object, required: Saved filter state — opaque JSON defined by the page
    - `columns` object, required: Column layout keyed by the page's own column IDs
      - `visibility` object, required
      - `order` string[], required
    - `sorting` object[], required: Saved sort order
      - `id` string, required
      - `direction` string, required
    - `visibility` 'public' | 'team' | 'private', required: Who can see the view
    - `isCollaborative` boolean, required: Whether viewers of a shared view may change it
    - `isSystem` boolean, required: Whether Atlas ships the view (never true for API-created views)
    - `position` integer, required: Order within the owner's own view list
    - `owner` object, required: The user who owns the view
      - `id` string, uuid, required
      - `name` string, required: "Deleted user" when the owner has been deleted
      - `deleted` boolean, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `415`: The request carried a body without `Content-Type: application/json`
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error
- `501`: Endpoint is disabled in this environment. Not a routing error — do not retry.

## Changes

- **2026-10-07** `0c873956b881`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/158ee454751c?raw)