> ## Documentation Index > Fetch the complete documentation index at: https://docs.attio.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a list > Creates a new list. Once you have your list, add attributes to it using the [Create attribute](/rest-api/endpoint-reference/attributes/create-an-attribute) API, and add records to it using the [Add records to list](/rest-api/endpoint-reference/entries/create-an-entry-add-record-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`. ## OpenAPI ````yaml https://api.attio.com/openapi/api post /v2/lists openapi: 3.1.0 info: title: Attio API version: 2.0.0 contact: name: Attio Support email: support@attio.com url: https://attio.com/help servers: - url: https://api.attio.com description: Production security: - oauth2: [] tags: - name: Objects description: >- Objects are the core data models inside of Attio. They contain standard objects, such as [people](/rest-api/endpoint-reference/standard-objects/people/list-person-records), [companies](/rest-api/endpoint-reference/standard-objects/companies/list-company-records) or [deals](/docs/standard-objects-deals), and custom objects that are specific to your use-case. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Object views description: Object views are saved table or board layouts for an object. - name: List views description: List views are saved table or board layouts for a list. - name: Attributes description: >- Attributes model properties of objects and lists. Some attributes, such as the `name` attribute on a person, are system-defined, while others are user-defined. Attributes are one of [many types](/docs/attribute-types) such as text, location or select. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Records description: >- Records are individual instances of objects e.g. a specific [person](/rest-api/endpoint-reference/standard-objects/people/list-person-records) or [company](/rest-api/endpoint-reference/standard-objects/companies/list-company-records). See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: SCIM groups description: >- SCIM groups represent Attio teams managed through the SCIM provisioning protocol. - name: SCIM schemas description: >- SCIM schemas describe the resource types supported by the SCIM service provider. - name: SCIM users description: >- SCIM users represent workspace members managed through the SCIM provisioning protocol. - name: Lists description: >- Lists are used to model a particular process. A list contains many records of a single object type, where each record is represented by an entry. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Meta description: Meta endpoints are used to get information about the API token. - name: Entries description: >- Entries are elements in a list that reference a single parent record. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [objects and lists guide](/docs/objects-and-lists) for more information. - name: Files description: >- Files are documents and folders linked to records, stored either in Attio or connected via external storage providers. - name: Workspace members description: >- Workspace members represent a user with access to a workspace. Workspace members are assigned roles that determine what they can do within the workspace. - name: Notes description: Notes are rich text documents that reference a single parent record. - name: Meetings description: >- Meetings are events synced from your calendar, added manually or added from third-party integrations. - name: Call recordings description: >- Call recordings store video, audio, transcript and speaker information for calls. They are linked to meetings. - name: Transcripts description: >- Transcripts contain the speech segments and speaker information for a call recording. They are linked to call recordings. - name: Tasks description: >- A task is a defined, actionable item with references to linked records and assigned workspace members. - name: Webhooks description: >- Webhooks allow you to listen for changes to data in Attio, for example when a record is updated. - name: Threads description: >- Threads are groups of [comments](/rest-api/endpoint-reference/comments/get-a-comment) on either a record or entry. - name: Comments description: >- Comments are messages on a [thread](/rest-api/endpoint-reference/threads/list-threads). - name: People description: >- People are one of the core objects inside of Attio. Person records can be added to lists and can be created automatically when syncing your mailbox. - name: Companies description: >- Companies are one of the core objects inside of Attio. Company records can be added to lists and can be created automatically when syncing your mailbox. - name: Users description: >- Users are an optional standard object that represents a user of your system. Users can belong to many workspaces. - name: Deals description: >- Deals are an optional standard object that represent a deal or opportunity. - name: Workspaces description: >- Workspaces are an optional standard object that represent a workspace or account in your system. Workspaces have many users and can be used to model a multi-tenant system. A company record can optionally have multiple workspaces. paths: /v2/lists: post: tags: - Lists summary: Create a list description: >- Creates a new list. Once you have your list, add attributes to it using the [Create attribute](/rest-api/endpoint-reference/attributes/create-an-attribute) API, and add records to it using the [Add records to list](/rest-api/endpoint-reference/entries/create-an-entry-add-record-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`. requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: name: type: string description: The human-readable name of the list. example: Enterprise Sales api_slug: type: string description: >- A unique, human-readable slug to access the list through API calls. Should be formatted in snake case. example: enterprise_sales parent_object: type: string description: >- A UUID or slug to identify the allowed object type for records added to this list. example: people workspace_access: type: - string - 'null' enum: - full-access - read-and-write - read-only 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. example: read-and-write workspace_member_access: type: array items: type: object properties: workspace_member_id: type: string format: uuid description: >- A UUID to identify the workspace member to grant access to. example: 50cf242c-7fa3-4cad-87d0-75b1af71c57b level: type: string enum: - full-access - read-and-write - read-only description: The level of access to the list. example: read-and-write required: - workspace_member_id - level description: >- The level of access granted to specific workspace members for this list. Pass an empty array to grant access to no workspace members. required: - name - api_slug - parent_object - workspace_access - workspace_member_access required: - data responses: '200': description: Success content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/list' required: - data description: Success '400': description: Bad Request content: application/json: schema: type: object properties: status_code: type: number enum: - 400 type: type: string enum: - invalid_request_error code: type: string enum: - value_not_found message: type: string example: >- Workspace member with ID "50cf242c-7fa3-4cad-87d0-75b1af71c57b" not found. required: - status_code - type - code - message description: Bad Request '403': description: Forbidden content: application/json: schema: type: object properties: status_code: type: number enum: - 403 type: type: string enum: - auth_error code: type: string enum: - billing_error message: type: string example: >- You attempted to create a List using permissions features that are not currently supported on your plan. Please upgrade, contact sales, or try a different access configuration for your list. required: - status_code - type - code - message description: Forbidden '404': description: Not Found content: application/json: schema: type: object properties: status_code: type: number enum: - 404 type: type: string enum: - invalid_request_error code: type: string enum: - not_found message: type: string example: Parent object with slug/ID "people" not found. required: - status_code - type - code - message description: Not Found '409': description: Conflict content: application/json: schema: type: object properties: status_code: type: number enum: - 409 type: type: string enum: - invalid_request_error code: type: string enum: - slug_conflict message: type: string example: A list with api_slug "my_list" already exists. required: - status_code - type - code - message description: Conflict security: - oauth2: - list_configuration:read-write components: schemas: list: type: object properties: id: type: object properties: workspace_id: type: string format: uuid description: A UUID to identify the workspace this list belongs to. example: 14beef7a-99f7-4534-a87e-70b564330a4c list_id: type: string format: uuid description: A UUID to identify this list. example: 33ebdbe9-e529-47c9-b894-0ba25e9c15c0 required: - workspace_id - list_id api_slug: type: string description: A human-readable slug for use in URLs and responses. example: hiring-engineering name: type: string description: The name of the list, as viewed in the UI. example: Hiring Engineering parent_object: type: array items: type: string 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. example: - people workspace_access: type: - string - 'null' enum: - full-access - read-and-write - read-only 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. example: read-and-write workspace_member_access: type: array items: type: object properties: workspace_member_id: type: string format: uuid description: A UUID to identify the workspace member to grant access to. example: 50cf242c-7fa3-4cad-87d0-75b1af71c57b level: type: string enum: - full-access - read-and-write - read-only description: The level of access to the list. example: read-and-write required: - workspace_member_id - level 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. created_by_actor: type: object description: The actor which created this list. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b created_at: type: string description: When the list was created. example: '2022-11-21T13:22:49.061281000Z' required: - id - api_slug - name - parent_object - workspace_access - workspace_member_access - created_by_actor - created_at securitySchemes: oauth2: type: oauth2 description: This API uses OAuth 2.0 with the authorization code grant flow. flows: authorizationCode: authorizationUrl: https://app.attio.com/authorize tokenUrl: https://app.attio.com/oauth/token scopes: user_management:read: View workspace members. user_management:read-write: View workspace members. record_permission:read: View, and optionally write, records. record_permission:read-write: View, and optionally write, records. object_configuration:read: >- View, and optionally write, the configuration and attributes of objects. object_configuration:read-write: >- View, and optionally write, the configuration and attributes of objects. list_entry:read: View, and optionally write, the entries in a list. list_entry:read-write: View, and optionally write, the entries in a list. list_configuration:read: >- View, and optionally write, the configuration and attributes of lists. list_configuration:read-write: >- View, and optionally write, the configuration and attributes of lists. public_collection:read: >- View, and optionally write, both the settings and information within public collections. public_collection:read-write: >- View, and optionally write, both the settings and information within public collections. private_collection:read: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. private_collection:read-write: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. comment:read: View comments (and threads), and optionally write comments. comment:read-write: View comments (and threads), and optionally write comments. task:read: View, and optionally write, tasks. task:read-write: View, and optionally write, tasks. note:read: View, and optionally write, notes. note:read-write: View, and optionally write, notes. meeting:read: View, and optionally write, meetings. meeting:read-write: View, and optionally write, meetings. call_recording:read: >- View, and optionally write, call recordings, transcripts and speakers for meetings. call_recording:read-write: >- View, and optionally write, call recordings, transcripts and speakers for meetings. webhook:read: View, and optionally manage, webhooks. webhook:read-write: View, and optionally manage, webhooks. file:read: View, and upload files. file:read-write: View, and upload files. ````