Object Model

In order to fully leverage the capabilities of our API, it is important to understand how the range of different Box objects fit together. Below you will find the core entities and their relationships, as well as detailed descriptions of each and links to further information.


Admins can manage users and groups, view and edit all of their organization’s files and folders, log in to any user’s account within their organization, edit settings for their organization, and run or access reports.

Bookmark (Weblink)

You can save shared links to Box content as bookmarks, helping you quickly find heavily accessed files and folders without needing to filter through layers of sub-folders. You can also link to other file types (Google Docs, HTML) as well as any other web URL.


Collaborations are Box’s equivalent of access control lists. They can be used to set and apply permissions for users or groups to folders. The collaboration roles that are currently available are editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, or owner. You can learn more about collaboration roles here


Collections store information about the items they contain, including files and folders. The only collection available currently is the “Favorites” collection. The contents of the collection are discovered in the same way as the contents of a folder.


Comments are messages generated by Box users. Each message is tied to a specific file. You can create comments independently or create them as responses to other comments.


Object that represents the organization using Box.


There are two types of events in Box: user events and admin events.

User events are focused on delivering a low latency, highly reliable list of all events relevant to a user's Box account. Events are registered against a time-sequenced list we call the stream_position.

Admin events are focused on delivering the full history of an enterprise account, and are useful for loading tools like Splunk, GoodData, and Analytics integrations. Admin events mirror the events available in our admin-logs, and support filtering by events type.


Files have attributes, such as who created the file, when it was last modified, and other information. The actual content of the file itself is accessible through the /files/{id}/content endpoint.


Folders contain information about the items they contain, including files and other folders. There is also an associated set of metadata including who owns the folder and when it was last modified.


Groups are defined sets of users. By using Groups, Admins and users with Group permissions have the ability to add multiple users to folders and assign access permissions quickly and easily.


This is the parent object to the File, Folder, and Collection objects. All Item objects have metadata and versions.

Metadata & Metadata Templates

Metadata allows users and applications to define and store custom, structured data associated with their files or folders. Metadata consists of key:value pairs.

Metadata that belongs to a file is grouped by templates. Metadata Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields.

Service Account

A Service Account represents your application within a Box Enterprise. Using a Service Account your application can authenticate to Box instead of authenticating as a user.


Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on that file.


There are three types of users: Managed Users, External Users, and App Users.

  • A Managed User is a Box user, created by an Admin within an enterprise, who accesses Box through our web and mobile apps. In addition, a Managed User can use Box's partner integrations.
  • An External User is a Box user that has been invited to collaborate on content in a Managed User's Box account via a collaboration invitation. This user has a Box account, however it belongs to a different enterprise than that of a Managed User. External Users listed in the Admin Console do not belong to your enterprise.
  • An App User is a Box account that belongs to your Box Platform application, not an end-user of Box. Unlike typical Box accounts, these accounts do not have an associated login and can only be accessed through the Box API.

If you have any questions, please visit our developer forum.

Object Model