Folder

A full representation of a folder, as can be returned from any folder API endpoints by default

This resource has a few variations that can be encountered when using the API.

The fields that are part of the full variant can be returned by API endpoints that support the fields parameter. For example, by defining the fields request parameter as id,type when requesting a file by ID, only those fields will be returned in the API response.

string
12345

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folders/123 the folder_id is 123.

string
folder

Value is always folder

string
1

The HTTP etag of this folder. This can be used within some API endpoints in the If-Match and If-None-Match headers to only perform changes on the folder if (no) changes have happened.

string
Contracts

The name of the folder.

3

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

string / date-time
2012-12-12T10:53:43-08:00

The date and time at which this folder was originally created.

string / date-time
2012-12-12T10:53:43-08:00

The date and time at which this folder was last updated.

string / date-time
2012-12-12T10:53:43-08:00

The date and time when the folder was created. This value may be null for some folders such as the root folder or the trash folder.

object

The user who created this folder

11446498

The unique identifier for this user

user

Value is always user

string / email
ceo@example.com

The primary email address of this user

Aaron Levie50

The display name of this user

Legal contracts for the new ACME deal256

The optional description of this folder

string / date-time
2012-12-12T10:53:43-08:00

The time and which the folder will be automatically be deleted.

open

When this parameter has been set, users can email files to the email address that has been automatically created for this folder.

To create an email address, set this property either when creating or updating the folder.

When set to collaborators, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered.

When set to open it will accept emails from any email address.

Value is one of open,collaborators

upload.Contracts.asd7asd@u.box.com

The optional upload email address for this folder.

A page of the items that are in the folder.

This field can only be requested when querying a folder's information, not when querying a folder's items.

active

Defines if this item has been deleted or not.

  • active when the item has is not in the trash
  • trashed when the item has been moved to the trash but not deleted
  • deleted when the item has been permanently deleted.

Value is one of active,trashed,deleted

string / date-time
2012-12-12T10:53:43-08:00

The date and time when the folder was last updated. This value may be null for some folders such as the root folder or the trash folder.

The user who last modified this folder.

11446498

The unique identifier for this user

user

Value is always user

string / email
ceo@example.com

The primary email address of this user

Aaron Levie50

The display name of this user

object

The user who owns this folder.

11446498

The unique identifier for this user

user

Value is always user

string / email
ceo@example.com

The primary email address of this user

Aaron Levie50

The display name of this user

object

The optional folder that this folder is located within.

This value may be null for some folders such as the root folder or the trash folder.

string
12345

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folders/123 the folder_id is 123.

folder

Value is always folder

1

The HTTP etag of this folder. This can be used within some API endpoints in the If-Match and If-None-Match headers to only perform changes on the folder if (no) changes have happened.

Contracts

The name of the folder.

3

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

The tree of folders that this folder is contained in, starting at the root.

The parent folders for this item

12345

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folders/123 the folder_id is 123.

folder

Value is always folder

1

The HTTP etag of this folder. This can be used within some API endpoints in the If-Match and If-None-Match headers to only perform changes on the folder if (no) changes have happened.

Contracts

The name of the folder.

3

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

1

The number of folders in this list.

string / date-time
2012-12-12T10:53:43-08:00

The time at which this folder is expected to be purged from the trash.

integer / int64
629644

The folder size in bytes.

Be careful parsing this integer as its value can get very large.

string / date-time
2012-12-12T10:53:43-08:00

The time at which this folder was put in the trash.

["editor"]

A list of the types of roles that user can be invited at when sharing this folder.

true

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

true

Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder.

It also restricts non-owners from inviting new collaborators.

Details about the classification applied to this folder.

#FF0000

The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app.

Content that should not be shared outside the company.

An explanation of the meaning of this classification.

Top Secret

The name of the classification

true

Specifies if this folder has any other collaborators.

true

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

true

Specifies if this folder is owned by a user outside of the authenticated enterprise.

Describes the permissions that the current user has for this folder

true

Specifies if the current user can delete this item.

true

Specifies if the current user can download this item.

true

Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item.

true

Specifies if the user can rename this item.

true

Specifies if the user can change the access level of an existing shared link on this item.

true

Specifies if the user can create a shared link for this item.

true

Specifies if the user can upload into this folder.

string
synced

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Value is one of synced,not_synced,partially_synced

string array
["approved"]

The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.

To add or remove a tag, retrieve the item's current tags, modify them, and then update this field.

There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

Details about the watermark applied to this folder

true

Specifies if this item has a watermark applied.

Response Example

{
  "id": 12345,
  "type": "folder",
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "description": "Legal contracts for the new ACME deal",
  "etag": 1,
  "expires_at": "2012-12-12T10:53:43-08:00",
  "folder_upload_email": {
    "access": "open",
    "email": "upload.Contracts.asd7asd@u.box.com"
  },
  "item_collection": {
    "entries": [
      {
        "id": 11446498,
        "type": "file",
        "sequence_id": 3,
        "etag": 1,
        "name": "Pictures",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": 12345,
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "url": "https://www.example.com/example/1234"
      }
    ],
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "total_count": 5000
  },
  "item_status": "active",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "name": "Contracts",
  "owned_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "parent": {
    "id": 12345,
    "type": "folder",
    "etag": 1,
    "name": "Contracts",
    "sequence_id": 3
  },
  "path_collection": {
    "entries": [
      {
        "id": 12345,
        "etag": 1,
        "type": "folder",
        "sequence_id": 3,
        "name": "Contracts"
      }
    ],
    "total_count": 1
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "sequence_id": 3,
  "shared_link": {
    "access": "open",
    "download_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "size": 629644,
  "trashed_at": "2012-12-12T10:53:43-08:00"
}