Create a list

v1.0.0

Creates a new list.

Once you have your list, add attributes to it using the API, and add records to it using the 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.

Input

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "api_slug",
        "name",
        "parent_object",
        "workspace_access",
        "workspace_member_access"
      ],
      "properties": {
        "api_slug": {
          "type": "string",
          "description": "A unique, human-readable slug to access the list through API calls. Should be formatted in snake case."
        },
        "name": {
          "type": "string",
          "description": "The human-readable name of the list."
        },
        "parent_object": {
          "type": "string",
          "description": "A UUID or slug to identify the allowed object type for records added to this list."
        },
        "workspace_access": {
          "type": [
            "string",
            "null"
          ],
          "description": "The level of access granted to all members of the workspace for this list. Pass `null` to keep the list private and only grant access to specific workspace members.",
          "enum": [
            "full-access",
            "read-and-write",
            "read-only"
          ]
        },
        "workspace_member_access": {
          "type": "array",
          "description": "The level of access granted to specific workspace members for this list. Pass an empty array to grant access to no workspace members.",
          "items": {
            "type": "object",
            "required": [
              "workspace_member_id",
              "level"
            ],
            "properties": {
              "level": {
                "type": "string",
                "description": "The level of access to the list.",
                "enum": [
                  "full-access",
                  "read-and-write",
                  "read-only"
                ]
              },
              "workspace_member_id": {
                "type": "string",
                "format": "uuid",
                "description": "A UUID to identify the workspace member to grant access to."
              }
            }
          }
        }
      }
    }
  }
}

Output

{
  "type": "object",
  "description": "Success",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "api_slug",
        "created_at",
        "created_by_actor",
        "id",
        "name",
        "parent_object",
        "workspace_access",
        "workspace_member_access"
      ],
      "properties": {
        "api_slug": {
          "type": "string",
          "description": "A human-readable slug for use in URLs and responses."
        },
        "created_at": {
          "type": "string",
          "description": "When the list was created."
        },
        "created_by_actor": {
          "type": "object",
          "description": "The actor which created this list.",
          "properties": {
            "id": {
              "type": "string",
              "description": "An ID to identify the actor."
            },
            "type": {
              "type": "string",
              "description": "The type of actor. [Read more information on actor types here](/docs/actors).",
              "enum": [
                "api-token",
                "workspace-member",
                "system",
                "app"
              ]
            }
          }
        },
        "id": {
          "type": "object",
          "required": [
            "list_id",
            "workspace_id"
          ],
          "properties": {
            "list_id": {
              "type": "string",
              "format": "uuid",
              "description": "A UUID to identify this list."
            },
            "workspace_id": {
              "type": "string",
              "format": "uuid",
              "description": "A UUID to identify the workspace this list belongs to."
            }
          }
        },
        "name": {
          "type": "string",
          "description": "The name of the list, as viewed in the UI."
        },
        "parent_object": {
          "type": "array",
          "description": "A UUID or slug to identify the allowed object type for records added to this list. All new Lists are expected to have exactly one parent object. However, some legacy lists may have multiple allowed parents so the return type of this field is an array.",
          "items": {
            "type": "string"
          }
        },
        "workspace_access": {
          "type": [
            "string",
            "null"
          ],
          "description": "The level of access granted to all members of the workspace for this list. `null` values represent a private list that only grants access to specific workspace members via the `workspace_member_access` property.",
          "enum": [
            "full-access",
            "read-and-write",
            "read-only"
          ]
        },
        "workspace_member_access": {
          "type": "array",
          "description": "The level of access granted to specific workspace members for this list. An empty array represents a list that has granted access to no workspace members.",
          "items": {
            "type": "object",
            "required": [
              "workspace_member_id",
              "level"
            ],
            "properties": {
              "level": {
                "type": "string",
                "description": "The level of access to the list.",
                "enum": [
                  "full-access",
                  "read-and-write",
                  "read-only"
                ]
              },
              "workspace_member_id": {
                "type": "string",
                "format": "uuid",
                "description": "A UUID to identify the workspace member to grant access to."
              }
            }
          }
        }
      }
    }
  }
}