Lists

Create a list

Creates a new list.

Once you have your list, add attributes to it using the Create attribute API, and add records to it using the Add records to list API.

New lists must specify which records can be added with the parent_object parameter which accepts either an object slug or an object ID. Permissions for the list are controlled with the workspace_access and workspace_member_access parameters.

Please note that new lists must have either workspace_access set to "full-access" or one or more element of workspace_member_access with a "full-access" level. It is also possible to receive a 403 billing error if your workspace is not on a plan that supports either advanced workspace or workspace member-level access for lists.

Required scopes: list_configuration:read-write.

post/v2/lists

Request body

Example request

{
  "data": {
    "name": "Enterprise Sales",
    "api_slug": "enterprise_sales",
    "parent_object": "people",
    "workspace_access": "read-and-write",
    "workspace_member_access": [
      {
        "workspace_member_id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
        "level": "read-and-write"
      }
    ]
  }
}

Response

Success

Example response

{
  "data": {
    "id": {
      "workspace_id": "14beef7a-99f7-4534-a87e-70b564330a4c",
      "list_id": "33ebdbe9-e529-47c9-b894-0ba25e9c15c0"
    },
    "api_slug": "hiring-engineering",
    "name": "Hiring Engineering",
    "parent_object": [
      "people"
    ],
    "workspace_access": "read-and-write",
    "workspace_member_access": [
      {
        "workspace_member_id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
        "level": "read-and-write"
      }
    ],
    "created_by_actor": {
      "type": "workspace-member",
      "id": "50cf242c-7fa3-4cad-87d0-75b1af71c57b"
    },
    "created_at": "2022-11-21T13:22:49.061281000Z"
  }
}

Changes

Changed in 2 of the 6 revisions of this API.11

Apr 24, 2025d2afbdc49fbc1See the full diff
- ●
  added the new missing_value enum value to the code response property for the response status 400
  response-property-enum-value-added
Apr 24, 20254ce2c28668d41See the full diff
- ○
  the endpoint scheme security oauth2 was removed from the API
  api-security-removed
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history