---
title: "Create a folder"
method: POST
path: "/v2/files"
tags: ["Files"]
---

# Create a folder

`POST /v2/files`

Creates a native folder entry or a connected file/folder entry on an object record.

This endpoint is in beta. We will aim to avoid breaking changes, but small updates may be made as we roll out to more users.

Required scopes: `file:read-write`, `object_configuration:read`, `record_permission:read`.

## Request body

- union
  - object
    - `object` string, required — The object slug or ID.
    - `record_id` string, uuid, required — The ID of the record to create the file entry on.
    - `file_type` 'folder', required — Creates a native Attio folder entry.
    - `name` string, required — The folder name.
    - `parent_folder_id` string, uuid — Optional parent folder ID. Omit to create a top-level folder.
  - object
    - `object` string, required — The object slug or ID.
    - `record_id` string, uuid, required — The ID of the record to create the file entry on.
    - `storage_provider` 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The external storage provider.
    - `external_provider_file_id` string, required — The ID of the file or folder in the external storage provider.
    - `microsoft_drive_id` string, nullable — Microsoft drive ID. Only used when `storage_provider` is `microsoft-onedrive`.
    - `file_type` 'connected-folder', required — Creates a connected folder entry.
  - object
    - `object` string, required — The object slug or ID.
    - `record_id` string, uuid, required — The ID of the record to create the file entry on.
    - `storage_provider` 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The external storage provider.
    - `external_provider_file_id` string, required — The ID of the file or folder in the external storage provider.
    - `microsoft_drive_id` string, nullable — Microsoft drive ID. Only used when `storage_provider` is `microsoft-onedrive`.
    - `file_type` 'connected-file', required — Creates a connected file entry.

## Response `200`

Success

- object — Success
  - `data` union, required
    - Folder
      - `id` object, required
        - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
        - `file_id` string, uuid, required — The ID of the file entry.
      - `object_id` string, uuid, required — The ID of the object the record belongs to.
      - `object_slug` string, required — The slug of the object the record belongs to.
      - `record_id` string, uuid, required — The ID of the record the file is linked to.
      - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
      - `created_by_actor` object, required — The actor that created this file entry.
        - `id` string, nullable — An ID to identify the actor.
        - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
      - `created_at` string, required — Timestamp representing when the file entry was created.
      - `file_type` 'folder', required — The type of file entry.
      - `name` string, required — The name of the folder.
      - `parent_folder_id` string, uuid, nullable, required — The ID of the parent folder, or null if this is a top-level folder.
    - ConnectedFile
      - `id` object, required
        - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
        - `file_id` string, uuid, required — The ID of the file entry.
      - `object_id` string, uuid, required — The ID of the object the record belongs to.
      - `object_slug` string, required — The slug of the object the record belongs to.
      - `record_id` string, uuid, required — The ID of the record the file is linked to.
      - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
      - `created_by_actor` object, required — The actor that created this file entry.
        - `id` string, nullable — An ID to identify the actor.
        - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
      - `created_at` string, required — Timestamp representing when the file entry was created.
      - `file_type` 'connected-file', required — The type of file entry.
      - `external_provider_file_id` string, required — The file ID in the external storage provider.
      - `microsoft_drive_id` string, nullable, required — Microsoft drive ID. This field is only populated for `microsoft-onedrive` entries.
    - ConnectedFolder
      - `id` object, required
        - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
        - `file_id` string, uuid, required — The ID of the file entry.
      - `object_id` string, uuid, required — The ID of the object the record belongs to.
      - `object_slug` string, required — The slug of the object the record belongs to.
      - `record_id` string, uuid, required — The ID of the record the file is linked to.
      - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
      - `created_by_actor` object, required — The actor that created this file entry.
        - `id` string, nullable — An ID to identify the actor.
        - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
      - `created_at` string, required — Timestamp representing when the file entry was created.
      - `file_type` 'connected-folder', required — The type of file entry.
      - `external_provider_file_id` string, required — The file ID in the external storage provider.
      - `microsoft_drive_id` string, nullable, required — Microsoft drive ID. This field is only populated for `microsoft-onedrive` entries.

---

[API](https://skmtc.net/attio/apis/attio-api.md) · [All operations](https://skmtc.net/attio/apis/attio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attio/attio-api/revisions/6ad6c02e6af9/schema)