Join BoxWorks 2024 to discover what's possible with content and AI!
Register now!A full representation of a folder, as can be returned from any folder API endpoints by default
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
folder
Value is always folder
["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
2012-12-12T10:53:43-08:00
The date and time at which this folder was originally created.
2012-12-12T10:53:43-08:00
The date and time at which this folder was last updated.
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.
The user who created this folder
Legal contracts for the new ACME deal
256
The optional description of this 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.
The folder_upload_email
parameter is not null
if one of the following options is true:
The Allow uploads to this folder via email and the Only allow email uploads from collaborators in this folder are enabled for a folder in the Admin Console, and the user has at least Upload permissions granted.
The Allow uploads to this folder via email setting is enabled for a folder in the Admin Console, and the Only allow email uploads from collaborators in this folder setting is deactivated (unchecked).
If the conditions are not met, the parameter will have the following value: folder_upload_email: null
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.
true
Specifies if this folder has any other collaborators.
true
This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.
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.
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 trashtrashed
when the item has been moved to the trash but not deleteddeleted
when the item has been permanently deleted.Value is one of active
,trashed
,deleted
An object containing the metadata instances that have been attached to this folder.
Each metadata instance is uniquely identified by its scope
and
templateKey
. There can only be one instance of any metadata
template attached to each folder. Each metadata instance is nested
within an object with the templateKey
as the key, which again
itself is nested in an object with the scope
as the key.
A list of metadata instances, nested within key-value pairs of their scope
and templateKey
.
An instance of a metadata template, which has been applied to a file or folder.
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.
Contracts
The name of the folder.
The user who owns this folder.
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.
The tree of folders that this folder is contained in, starting at the root.
The parent folders for this item
1
The number of folders in this list.
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 upload into this folder.
2012-12-12T10:53:43-08:00
The time at which this folder is expected to be purged from the trash.
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.
629644
The folder size in bytes.
Be careful parsing this integer as its value can get very large.
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
["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.
2012-12-12T10:53:43-08:00
The time at which this folder was put in the trash.
Details about the watermark applied to this folder
true
Specifies if this item has a watermark applied.
{
"id": "12345",
"type": "folder",
"allowed_invitee_roles": [
"editor"
],
"allowed_shared_link_access_levels": [
"open"
],
"can_non_owners_invite": true,
"can_non_owners_view_collaborators": true,
"classification": {
"color": "#FF0000",
"definition": "Content that should not be shared outside the company.",
"name": "Top Secret"
},
"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",
"folder_upload_email": {
"access": "open",
"email": "upload.Contracts.asd7asd@u.box.com"
},
"has_collaborations": true,
"is_accessible_via_shared_link": true,
"is_associated_with_app_item": true,
"is_collaboration_restricted_to_enterprise": true,
"is_externally_owned": true,
"item_collection": {
"entries": [
{
"id": "12345",
"etag": "1",
"type": "file",
"sequence_id": "3",
"name": "Contract.pdf",
"sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
"file_version": {
"id": "12345",
"type": "file_version",
"sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
},
"description": "Contract for Q1 renewal",
"size": 629644,
"path_collection": {
"total_count": 1,
"entries": [
{
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
]
},
"created_at": "2012-12-12T10:53:43-08:00",
"modified_at": "2012-12-12T10:53:43-08:00",
"trashed_at": "2012-12-12T10:53:43-08:00",
"purged_at": "2012-12-12T10:53:43-08:00",
"content_created_at": "2012-12-12T10:53:43-08:00",
"content_modified_at": "2012-12-12T10:53:43-08:00",
"created_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"modified_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"owned_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"shared_link": {
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
"vanity_url": "https://acme.app.box.com/v/my_url/",
"vanity_name": "my_url",
"access": "open",
"effective_access": "company",
"effective_permission": "can_download",
"unshared_at": "2018-04-13T13:53:23-07:00",
"is_password_enabled": true,
"permissions": {
"can_download": true,
"can_preview": true,
"can_edit": false
},
"download_count": 3,
"preview_count": 3
},
"parent": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
},
"item_status": "active",
"version_number": "1",
"comment_count": 10,
"permissions": {
"can_delete": true,
"can_download": true,
"can_invite_collaborator": true,
"can_rename": true,
"can_set_share_access": true,
"can_share": true,
"can_annotate": true,
"can_comment": true,
"can_preview": true,
"can_upload": true,
"can_view_annotations_all": true,
"can_view_annotations_self": true
},
"tags": [
"approved"
],
"lock": {
"id": "11446498",
"type": "lock",
"created_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"created_at": "2012-12-12T10:53:43-08:00",
"expired_at": "2012-12-12T10:53:43-08:00",
"is_download_prevented": true,
"app_type": "office_wopiplus"
},
"extension": "pdf",
"is_package": true,
"expiring_embed_link": {
"access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
"expires_in": 3600,
"token_type": "bearer",
"restricted_to": [
{
"scope": "item_download",
"object": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
}
],
"url": "https://cloud.app.box.com/preview/expiring_embed/..."
},
"watermark_info": {
"is_watermarked": true
},
"is_accessible_via_shared_link": true,
"allowed_invitee_roles": [
"editor"
],
"is_externally_owned": true,
"has_collaborations": true,
"metadata": {
"enterprise_27335": {
"marketingCollateral": {
"$canEdit": true,
"$id": "01234500-12f1-1234-aa12-b1d234cb567e",
"$parent": "folder_59449484661",
"$scope": "enterprise_27335",
"$template": "marketingCollateral",
"$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
"$typeVersion": 2,
"$version": 1
}
}
},
"expires_at": "2012-12-12T10:53:43-08:00",
"representations": {
"entries": [
{
"content": {
"url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
},
"info": {
"url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
},
"properties": {
"dimensions": "2048x2048",
"paged": true,
"thumb": true
},
"representation": "png",
"status": {
"state": "success"
}
}
]
},
"classification": {
"name": "Top Secret",
"definition": "Content that should not be shared outside the company.",
"color": "#FF0000"
},
"uploader_display_name": "Ellis Wiggins",
"disposition_at": "2012-12-12T10:53:43-08:00",
"shared_link_permission_options": [
"can_preview"
],
"is_associated_with_app_item": true
}
],
"limit": 1000,
"next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
"offset": 2000,
"order": [
{
"by": "type",
"direction": "ASC"
}
],
"prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
"total_count": 5000
},
"item_status": "active",
"metadata": {
"enterprise_27335": {
"marketingCollateral": {
"$canEdit": true,
"$id": "01234500-12f1-1234-aa12-b1d234cb567e",
"$parent": "folder_59449484661",
"$scope": "enterprise_27335",
"$template": "marketingCollateral",
"$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
"$typeVersion": 2,
"$version": 1
}
}
},
"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
},
"permissions": {
"can_delete": true,
"can_download": true,
"can_invite_collaborator": true,
"can_rename": true,
"can_set_share_access": true,
"can_share": true,
"can_upload": true
},
"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_edit": false,
"can_preview": true
},
"preview_count": 3,
"unshared_at": "2018-04-13T13:53:23-07:00",
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"vanity_name": "my_url",
"vanity_url": "https://acme.app.box.com/v/my_url/"
},
"size": 629644,
"sync_state": "synced",
"tags": [
"approved"
],
"trashed_at": "2012-12-12T10:53:43-08:00",
"watermark_info": {
"is_watermarked": true
}
}