Box Developer Platform

Suggest Edits

Overview

The Box API gives you access to a set of secure content management features for use in your own app, such as file storage, preview, search, commenting, and metadata. It strives to be RESTful and is organized around the main resources from the Box web interface.

 

Box API Overview

The Box API gives you access to a set of secure content management features for use in your own app, such as file storage, preview, search, commenting, and metadata. It strives to be RESTful and is organized around the main resources from the Box web interface.

Before you do anything, you should create a free Box account that you can test the API against and register for an API key so that you can make API calls.

If you are building custom applications for users with a Box account, you can follow the authentication instructions using OAuth 2.

If you are building custom applications and wish to leverage the Box API without requiring a Box account, you will need to use Box Platform. You can find a tutorial for building with Box Platform here.

Example Requests

Sample API calls are provided next to each method using cURL, a standard command line tool. All you need to do is drop in your specific parameters, and you can test the calls from the command line. If the command line isn’t your preference, a great alternative is Postman, an easy-to-use Chrome extension for making HTTP requests. Or you can always use one of our SDKs instead of making direct API calls.

Input/Output Format

Both request body data and response data are formatted as JSON. Extremely large numbers (for example the folder size) will be returned in IEEE754 format (the same way doubles are stored in Java), e.g. 1.2318237429383e+31. Ids like FOLDER_ID and FILE_ID are unsigned big integers using 64 bits in the range 0 to 18446744073709551615.

Date Format

All timestamps (both those sent in requests and those returned in responses) should be formatted as shown in our examples. We support RFC 3339 timestamps. The preferred way to pass in a date is by converting the time to UTC such as this: 2013-04-17T09:12:36-00:00.

In cases where timestamps are rounded to a given day, you may omit the time component. So instead of 2013-04-17T13:35:01+05:00 you can use 2013-04-17. If a time (and not just a date) however, is specified in a request then the calendar date in the Pacific timezone at the moment specified is the day that is accepted.

Box supports the subset of dates after the start of the Unix epoch: 1970-01-01T00:00:00+00:00 (00:00:00 UTC on January 1, 1970).

As a note, the timestamp you receive from the Box API is based on the settings in the Admin console. If you are a part of an enterprise, it will be the default user settings set by your admin.

gzip

If you would like responses from Box to be compressed for faster response times, simply include an Accept-Encoding header with a value of gzip, deflate, and responses will be gzipped.

Getting Help

If you have any questions or feedback, please post on the Box developer forum.

Suggest Edits

Suppressing Notifications

 

If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications by including a Box-Notifications header with the value off. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email saying “The Acme-Virus-scanner just downloaded your “Acme exploding tennis balls instructions”. All actions will still appear in users updates feed and the audit-logs.

Notification suppression is available to be turned on for approved applications only. Contact us to explain your application’s use of notification suppression.

Note

User creation, comment, collaboration creation, change user's login, and task assignment notifications cannot be suppressed using this header.

CORS, or cross-origin resource sharing, is a mechanism that allows a web page to make XMLHttpRequests to another domain (i.e. a domain different from the one it was loaded from). CORS is supported in a specific set of modern browsers. The Box API supports CORS on an app-by-app basis. You can add a comma separated list of origins that can make CORS requests to the API, through the developer console.

A quick tutorial can be found here.

CORS Downloads

CORS is not supported for downloading content.

CORS-Like Errors

Some browsers will return a CORS-like error, even when CORS is enabled for your application. In these scenarios, an HTTP response code will often be included (e.g. 400 or 401) which will provide further direction where you may want to focus troubleshooting. No further CORS enablement is done in the Box backend.

Suggest Edits

Pagination

 

Endpoints that return collections support limit and offset or marker as URL parameters. Limit defines the maximum number of records that will be returned on a page. The number of records is not guaranteed to be the number specified as visibility rules may filter out items. To avoid duplicates being returned we recommend the following logic:

  1. To retrieve the next page, set offset=offset+limit
  2. If total count from previous response is >= the new offset, you are done, no need to ask for another page

Note that offset is zero based, defaults for limit vary by endpoint.

Suggest Edits

Errors

The Box API communicates errors through standard HTTP status codes with details supplied in JSON objects. Generally the following pattern applies:

 
  • 2xx - Box received, understood, and accepted a request.
  • 3xx - The user agent must take further action in order to complete the request.
  • 4xx - An error occurred in handling the request. The most common cause of this error is an invalid parameter.
  • 5xx- Box received and accepted the request, but an error occurred in the Box service while handling it.

HTTP Status Codes

200 success
201 created
202 accepted
204 no_content
302 redirect
304 not_modified
400 bad_request
401 unauthorized
403 forbidden
404 not_found
405 method_not_allowed
409 conflict
412 precondition_failed
429 too_many_requests
500 internal_server_error
503 unavailable

Error Code Response

Name
Error

type

string

"error" in error responses.

status

int

The HTTP status of the response.

code

string

A specific Box error code listed here

context_info

object

Additional context information describing the error.

context_info.errors

array

An array of error objects giving context for the error; each object includes reason, name, and message properties.

help_url

string

A URL that links to more information about why the error occurred.

message

string

A human-readable message describing the error.

request_id

string

A unique ID that identifies this request. The ID can be helpful when troubleshooting requests.

EXAMPLE ERROR

{
    "type": "error",
    "status": 409,
    "code": "conflict",
    "context_info": {
        "errors": [
            {
                "reason": "invalid_parameter",
                "name": "group_tag_name",
                "message": "Invalid value 'All Box '. A resource with value 'All Box ' already exists"
            }
        ]
    },
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Resource with the same name already exists",
    "request_id": "2132632057555f584de87b7"
}

Detailed Error Codes

The following table lists the most common error responses you are likely to see when developing Box applications. This list is not exhaustive; additional errors can occur. If your application handles all of these responses, though, then it's likely to be a robust application that gracefully handles the majority of user interactions and internet issues.

Box recommends that you begin by handling the most generic errors (for example, error codes 401 and 403), and then gradually add handling for more and more specific errors.

status
error_code
message

400

bad_request

400

item_name_invalid

Item name invalid

400

terms_of_service_required

User must accept custom terms of service before action can be taken

400

requested_preview_unavailable

Requested preview unavailable

400

folder_not_empty

Cannot delete – folder not empty

400

invalid_request_parameters

Invalid input parameteres in request

400

user_already_collaborator

User is already a collaborator

400

cannot_make_collaborated_subfolder_private

Cannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified

400

item_name_too_long

Item name too long

400

collaborations_not_available_on_root_folder

Root folder cannot be collaborated

400

sync_item_move_failure

Cannot move a synced item

400

requested_page_out_of_range

Requested representation page out of range

400

cyclical_folder_structure

Folder move creates cyclical folder structure

400

bad_digest

The specified Content-MD5 did not match what we received

400

invalid_collaboration_item

Item type must be specified and set to ‘folder’

400

task_assignee_not_allowed

Assigner does not have sufficient privileges to assign task to assignee

400

invalid_status

You can change the status only if the collaboration is pending

401

unauthorized

Unauthorized

403

forbidden

403

storage_limit_exceeded

Account storage limit reached

403

access_denied_insufficient_permissions

Access denied – insufficient permission

403

access_denied_item_locked

Access denied – item locked

403

file_size_limit_exceeded

File size exceeds the folder owner’s file size limit

403

incorrect_shared_item_password

403

access_from_location_blocked

You’re attempting to log in to Box from a location that has not been approved by your admin. Please talk to your admin to resolve this issue.

404

not_found

404

preview_cannot_be_generated

Preview cannot be generated

404

trashed

Item is trashed

404

not_trashed

Item is not trashed

405

method_not_allowed

Method Not Allowed

409

item_name_in_use

Item with the same name already exists

409

conflict

A resource with this value already exists

409

user_login_already_used

User with the specified login already exists

409

recent_similar_comment

A similar comment has been made recently

409

operation_blocked_temporary

The operation is blocked by another ongoing operation.

412

sync_state_precondition_failed

The resource has been modified. Please retrieve the resource again and retry

412

precondition_failed

The resource has been modified. Please retrieve the resource again and retry

429

rate_limit_exceeded

Request rate limit exceeded, please try again later

500

internal_server_error

Internal Server Error

503

unavailable

Unavailable

Suggest Edits

Fields

By default, each object has a standard and a mini format.

 
  • The standard format is returned when you request a specific object (e.g. GET /files/{id}).
  • The mini is returned when the object is part of a collection of items (e.g. GET /files/{id}/comments).

If you do not want the standard or the mini formats to be returned, you can optionally use the fields URL parameter to specify a comma-separated list of the specific fields you’d like returned. If you specify the fields parameter, only the fields you request are returned along with the ID and item type. For example, GET /files/{id}?fields=modified_at,path_collection,name is a valid request, but will only return the modified_path, path_collection, name, id, and item_type.

Some fields are not included in the standard format, and can only be retrieved if you request them using the fields URL parameter. These fields are listed as italicized in the object definitions.

Fields Support:

The fields parameter is not yet supported for GET /events, POST /files/content, and POST /files/{id}/content.

EXAMPLE REQUEST

curl https://api.box.com/2.0/files/FILE_ID?fields=modified_at,path_collection,name
-H "Authorization: Bearer ACCESS_TOKEN"

EXAMPLE RESPONSE

{
    "type": "file",
    "id": "3447956798",
    "etag": "1",
    "modified_at": "2012-10-04T12:34:05-07:00",
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
               	"sequence_id": null,
              	"etag": null,
                "name": "All Files"
           },
           {
               "type": "folder",
               "id": "423404344",
               "sequence_id": "15",
               "etag": "15",
               "name": "General Info"
           }
       ]
   },
   "name": "Org Chart.PDF"
}
Suggest Edits

If-Match

The Box API supports the HTTP If-Match and If-None-Match headers for certain methods in the files and folders endpoints (Supported methods are listed below). If-Match headers let you ensure that your app only alters files/folders on Box if you have the current version; similarly, If-None-Match headers ensure that you don’t retrieve unnecessary data if you already have the most current version on-hand.

 

Etags

Every files and folders object has an etag attribute that is unique across every version of that file or folder. Etags are unique across versions of items, but not across different items. For example, the first version of File XYZ can have an etag value of “1”, and the first version of File ABC “1”, but any other version of File XYZ must have an etag value that is not “1”.

Etag:

You should make no assumptions about the value of etags outside of the fact that they are unique for each version of particular file or folder relative to other versions of that file or folder.

Using If-(None-)Match

The methods that can be used with If-Match are listed on the right. The following tables summarize the behavior you can expect when using If-Match:

If-Match Header Has Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 200

RESOURCE DOES NOT EXIST

HTTP Status of Response: 412

If-Match Header Does Not Have Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 412

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

The following behavior will be found with the If-None-Match header:

If-None-Match Header Has Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 304

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

If-None-Match Header Does Not Have Most Current Etag

RESOURCE EXISTS

HTTP Status of Response: 200

RESOURCE DOES NOT EXIST

HTTP Status of Response: 404

IF-MATCH SUPPORTED METHODS

POST /files/{id}/content
PUT /files/{id}
DELETE /files/{id}
PUT /folders/{id}
DELETE /folders/{id}

IF-NONE-MATCH SUPPORTED METHODS

GET /files/{id}
GET /folders/{id}
GET /shared_items
Suggest Edits

As-User

The As-User header is used by enterprise administrators to make API calls for their managed users. It can also be used by a Service Account to make API calls for managed users or app users.

You will have to pass in the header As-User: USER_ID to impersonate the user within the enterprise. These API calls require the requests to come from an Admin, a Co-admin, or a Service Account to be successful.

To enable this functionality for applications using OAuth2, please file a support ticket with your API key.

To enable this functionality for applications using OAuth2 with JWT, please navigate to the Advanced Features section in the developer console and enable the "Perform actions on behalf of users" permission.

 

Note:

Admins can use As-User to impersonate any managed users including co-admins. Co-admins can use As-User to impersonate managed users, but cannot impersonate any admin or co-admin. A 403 Forbidden error will be returned.

As-User has replaced the previous On-Behalf-Of functionality. As-User is more robust because it is tied to a static user_id instead of a dynamic email address that may change. On-Behalf-Of functionality will continue to be supported, but we recommend migrating to the As-User header.

EXAMPLE REQUEST (with standard OAuth 2.0)

curl https://api.box.com/2.0/folders/0?fields=item_collection,name \
-H "Authorization: Bearer ACCESS_TOKEN_OF_THE_ADMIN" \
-H "As-User: 10543463" 

EXAMPLE RESPONSE

{
 "type": "folder",
    "id": "0",
    "etag": null,
    "name": "All Files",
    "item_collection": {
        "total_count": 4,
        "entries": [
            {
                "type": "folder",
                "id": "494447198",
                "etag": "0",
                "name": "Archive"
            },
            {
                "type": "folder",
                "id": "611745226",
                "etag": "1",
                "name": "Customer Info"
            },
            {
                "type": "folder",
                "id": "329767175",
                "etag": "0",
                "name": "Vendors"
            },
            {
                "type": "folder",
                "id": "632559865",
                "etag": "0",
                "name": "Human Resources"
            }
        ],
        "offset": 0,
        "limit": 100,
        "order": [
            {
                "by": "type",
                "direction": "ASC"
            },
            {
                "by": "name",
                "direction": "ASC"
            }
        ]
    }
}
Suggest Edits

Rate Limiting

In certain cases, Box needs to enforce rate-limiting in order to prevent abuse by third-party services and/or users. In the event that an excessive level of usage is reached, a standard 429 Too Many Requests error will be returned, with an indication of when to retry the request. In the event that back-to-back 429s are received, an exponential backoff algorithm is recommended.

 

RETRY HEADER

HTTP/1.1 429 Too Many Requests
Retry-After: {retry time in seconds}
 

Box uses OAuth 2.0 to authenticate connections that use the Box APIs. OAuth 2 is an open protocol for authentication used with web, mobile, and desktop applications. Every use of Box APIs requires authentication so that Box can ensure that only authorized users can interact with Box content. OAuth 2 is the protocol that Box uses for such authentication.

Box uses the standard OAuth 2 three-legged authentication process, which proceeds as follows:

  1. The application asks an authentication service to present a login request to a user.
  2. After a successful login, the authentication service returns an authorization code to the application.
  3. The application exchanges the authorization code for an access token.

The application can then use the access token with API requests to gain access to the user's resources by including the token in an authorization header named access_token.

The Box HTTP APIs provide full access to standard OAuth 2 authentication. You can use API calls to implement authentication for your applications. In addition, Box also provides several SDKs that manage OAuth 2 authentication for you, simplifying the authentication process for applications that are built on the SDKs.

For machine-to-machine use cases, such as applications that use Box services for back-end storage, but which provide their own user-inteface, Box extends OAuth 2 with JSON Web Tokens (JWT). Authentication using JWT enables your application to authenticate itself directly to Box without needing to display any Box user interface elements.

Whether you use plain OAuth 2 authentication and the Box login screen, or OAuth2 with JWT and your own user interface, and whether you use a Box SDK or build your authentication using direct API requests, your application uses the same authentication services used by Box products. You inherit all Box features, including the ability to work with single sign-on systems that support Box.

OAuth Endpoint

The HTTP endpoint for Box authentication is:

https://api.box.com/oauth2

Authorization Header

Following in the format of a Box authorization header:

Authorization: Bearer <MY_ACCESS_TOKEN>

You must replace <MY_ACCESS_TOKEN> with a valid access token returned to your application by Box.

Suggest Edits

Authorize

 

https://account.box.com/api/oauth2/authorize

This is the URL of the Box login endpoint. To begin the process of authenticating and authorizing an application to work with the Box APIs, send an HTTP request like the following:

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=<MY_CLIENT_ID>&redirect_uri=<MY_REDIRECT_URL>&state=<MY_SECURITY_TOKEN>

This request passes the following parameters:

Parameter
Description
Description

response_type

String

The type of OAuth 2 grant you are requesting. Use the value code.

client_id

String

The client ID of the application requesting authentication. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

redirect_uri

URI

The URL to which Box redirects the browser when authentication completes. The user's actual interaction with your application begins when Box redirects to this URL. You must supply the redirect URL in the configuration page of your application. It must be a valid HTTPS URL that resolves to a valid IP address. The IP address must not be a Box address, and there must be a working web service or application accessible at the address that can correctly handle Box requests.

state

String

A text string that you choose. Box sends the same string to your redirect URL when authentication is complete. This parameter is provided for your use in protecting against hijacked sessions and other attacks.

scope optional

String

This optional parameter identifies the Box scopes available to the application once it's authenticated. If you don't supply this parameter then Box grants access to the default scopes configured for the application in its configuration page. You can limit the scopes available to the application by passing a comma-separated list of Box scopes.

Note

The authorize endpoint uses a different URL from other Box API calls: account.box.com/api instead of api.box.com.

Example

Using the Authorize URL

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=security_token%3DKnhMJatFipTAnM0nHlZA

Example Response

<MY_REDIRECT_URI>?code=<MY_AUTHORIZATION_CODE>

https://api.box.com/oauth2/token

This is the URL of the Box token endpoint, the endpoint that returns access tokens. An access token is a data string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the Box authorize endpoint and Box will send you an authorization code. You will then send the authorization code to the token endpoint in a request for an access token. You can then use the returned access token to make Box API calls.

To exchange an authorization code for an access token, send a request like the following:

curl https://api.box.com/oauth2/token \
-d 'grant_type=authorization_code' \
-d 'code=<MY_AUTH_CODE>' \
-d 'client_id=<MY_CLIENT_ID>' \
-d 'client_secret=<MY_CLIENT_SECRET>' \
-X POST

The parameters used in this request are as follows:

Parameter
Type
Description

grant_type

String

authorization_code

code

String

The authorization code returned by Box in response to a successfull authentication request.

client_id

String

The client ID of the application requesting authentication. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

client_secret

String

The client secret of the application requesting authentication. To get the client secret for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_secret". The text of that item is your application's client secret.

Example

Using the Token URL

curl https://api.box.com/oauth2/token \
-d 'grant_type=authorization_code' \
-d 'code=<MY_AUTH_CODE>' \
-d 'client_id=<MY_CLIENT_ID>' \
-d 'client_secret=<MY_CLIENT_SECRET>' \
-X POST

Example Response

{
    "access_token": "T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl",
    "expires_in": 3600,
    "restricted_to": [],
    "token_type": "bearer",
    "refresh_token": "J7rxTiWOHMoSC1isKZKBZWizoRXjkQzig5C6jFgCVJ9bUnsUfGMinKBDLZWP9BgR"
}

https://api.box.com/oauth2/revoke

This is the URL of the Box revoke endpoint, the endpoint that revokes access tokens, or to put it another way, the endpoint that ends sessions, logging users out.

To revoke an access token, ending the session and loggingthe user out of Box, send a request like the following:

curl https://api.box.com/oauth2/revoke \
-d 'client_id=MY_CLIENT_ID' \
-d 'client_secret=MY_CLIENT_SECRET' \
-d 'token=MY_TOKEN' \
-X POST

The parameters sent with this request are as follows:

Parameter
Type
Description

client_id

String

The client ID of the application requesting revocation. To get the client ID for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_id". The text of that item is your application's client ID.

client_secret

String

The client secret of the application requesting authentication. To get the client secret for your application, log in to your Box developer console and click the Edit Application link for the application you're working with. In the OAuth 2 Parameters section of the configuration page, find the item labeled "client_secret". The text of that item is your application's client secret.

token

String

An access token or refresh token supplied by Box in response to a token request. When either token is supplied with this request, both will be revoked.

Suggest Edits

File Object

 

File information describe file objects in Box, with attributes like 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. Italicized attributes are not returned by default and must be retrieved through the fields parameter.

Supported Filenames:

Box only supports file names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with leading or trailing spaces, and the special names “.” and “..”.

type

string

For files is ‘file’.

id

string

Box’s unique string identifying this file.

file_version

object

The version information of the file.

sequence_id

string

A unique ID for use with the /events endpoint.

etag

string

A unique string identifying the version of this file.

sha1

string

The sha1 hash of this file.

name

string

The name of this file.

description

string

The description of this file.

size

integer

Size of this file in bytes.

path_collection

collection

The path of folders to this item, starting at the root.

created_at

timestamp

When this file was created on Box’s servers.

modified_at

timestamp

When this file was last updated on the Box servers.

trashed_at

timestamp

When this file was last moved to the trash.

purged_at

timestamp

When this file will be permanently deleted.

content_created_at

timestamp

When the content of this file was created (more info).

content_modified_at

timestamp

When the content of this file was last modified (more info).

created_by

mini user object

The user who first created file.

modified_by

mini user object

The user who last updated this file.

owned_by

mini user object

The user who owns this file.

shared_link

object

The shared link object for this file.

parent

mini folder object

The folder containing this file.

item_status

string

Whether this item is deleted or not. Values include active, trashed if the file has been moved to the trash, and deleted if the file has been permanently deleted.

version_number

string

The version number of the file.

comment_count

integer

The number of comments on a file.

permissions

object

The permissions that the current user has on this file. The keys are can_download, can_preview, can_upload, can_comment, can_rename, can_delete, can_share, and can_set_share_access. Each value is a boolean.

tags

array of strings

All tags applied to this file.

lock

object

The lock held on the file.

extension

string

Indicates the suffix, when available, on the file. By default, set to an empty string. The suffix usually indicates the encoding (file format) of the file contents or usage.

is_package

boolean

Whether the file is a package. Used for Mac Packages used by iWorks.

expiring_embed_link

string

An expiring URL for an embedded preview session in an iframe. This URL will expire after 60 seconds and the session will expire after 60 minutes.

watermark_info

object

Information about the watermark status of this file. See Watermarking for additional endpoints.

Fields:
is_watermarked (boolean): Whether the file is watermarked or not.

{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc "
    },
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-02-04T16:57:52-08:00",
    "content_modified_at": "2013-02-04T16:57:52-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active",
    "tags": [
        "cropped",
        "color corrected"
    ],
    "lock": {
        "type": "lock",
        "id": "112429",
        "created_by": {
            "type": "user",
            "id": "18212074",
            "name": "Obi Wan",
            "login": "obiwan@box.com"
        },
        "created_at": "2013-12-04T10:28:36-08:00",
        "expires_at": "2012-12-12T10:55:30-08:00",
        "is_download_prevented": false
    }
}
 
{
    "sequence_id": "0",
    "etag": "0",
    "type": "file",
    "id": "2631999573",
    "name":"IMG_1312.JPG"
}
Suggest Edits

Get File's Info

Used to retrieve the metadata about a file.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

Note

The download_url will only return a link for paid accounts.

Returns

A full file object is returned if the ID is valid and if the user has access to the file.

curl https://api.box.com/2.0/files/FILE_ID
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFile

public BoxFile.Info getInfo()
  
public BoxFile.Info getInfo(String... fields)
Files.prototype.get = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> GetInformationAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "type": "file",
    "id": "5000948880",
    "file_version": {
        "type": "file_version",
        "id": "26261748416",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}
Suggest Edits

Update File Info

Used to update individual or multiple fields in the file object, including renaming the file, changing its description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to prevent race conditions.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Body Params

name
string

The new name for the file.

description
string

The new description for the file.

parent
string

The parent folder of this file.

id
string

Child of parent. The ID of the parent folder.

shared_link
object

An object representing this item’s shared link and associated permissions.

 
access
string

Child of shared_link. The level of access required for this shared link. Can be open, company, collaborators.

unshared_at
date-time

Child of shared_link. The day that this link should be disabled at. Timestamps are rounded off to the given day.

permissions
object

Child of shared_link. The set of permissions that apply to this link.

 
download
boolean

Child of permissions. Whether this link allows downloads.

preview
boolean

Child of permissions. Whether this link allows previews.

tags
array of strings

All tags attached to this file. To add/remove a tag to/from a file, you can first get the file’s current tags (be sure to specify ?fields=tags, since the tags field is not returned by default); then modify the list as required; and finally, set the file’s entire list of tags.

Headers

If-Match
string

The etag of the file can be included as an ‘If-Match’ header to prevent race conditions.

Note:

Editing of passwords is currently not supported for shared links.

Returns

A full file object is returned if the ID is valid and if the user has access to the file.

curl https://api.box.com/2.0/files/FILE_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"new name.jpg"}' \
-X PUT
package com.box.sdk

public class BoxFile

public void updateInfo(BoxFile.Info info)
Files.prototype.update = function(fileID, options, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> UpdateInformationAsync(BoxFileRequest fileRequest, string etag = null, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "new name.jpg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}
Suggest Edits

Lock and Unlock

To lock and unlock files, you execute a PUT operation on the /files/{file id} endpoint and set or clear the lock properties on the file.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Body Params

lock
object
required

The lock object

 
type
string
required

Child of lock. Can be lock or unlock.

expires_at
date-time

Child of lock. The time the lock expires.

is_download_prevented
boolean

Child of lock. Whether or not the file can be downloaded while locked.

curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"lock": { "type": "lock","expires_at": "2015-12-12T10:55:30-08:00","is_download_prevented": false}}' \
-X PUT
curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"lock": null}' \
-X PUT
package com.box.sdk

public class BoxFile

public BoxLock lock(Date expiresAt, boolean isDownloadPrevented)

public void unlock()
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFileLock> UpdateLockAsync(BoxFileLockRequest lockFileRequest, string Id)
  
public async Task<bool> UnLock(string id)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Download File

Retrieves the actual data of the file. An optional version parameter can be set to download a previous version of the file.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/content

Path Params

file_id
string
required

Query Params

version
string

The ID specific version of this file to download.

Headers

Range
string

The range value in bytes. Format should be bytes={start_range}-{end_range}

BoxApi
string

The shared link for this item. Format should be shared_link=SHARED_LINK

Returns

If the file is available to be downloaded, the response will be a 302 Found to a URL at dl.boxcloud.com. The dl.boxcloud.com URL is not persistent. Clients will need to follow the redirect in order to actually download the file. The raw data of the file is returned unless the file ID is invalid or the user does not have access to it.

If the file is not ready to be downloaded (i.e. in the case where the file was uploaded immediately before the download request), a response with an HTTP status of 202 Accepted will be returned with a Retry-After header indicating the time in seconds after which the file will be available for the client to download.

Sample Call:

For convenience, the sample cURL request includes a -L flag that will automatically follow the redirect to boxcloud.com. To change this behavior, simply remove the -L from the sample call.

curl -L https://api.box.com/2.0/files/FILE_ID/content
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFile

public URL getDownloadURL()

public void downloadRange(OutputStream output, long rangeStart, long rangeEnd, ProgressListener listener)

public void download(OutputStream output, ProgressListener listener)
Files.prototype.getDownloadURL = function(fileID, qs, callback)

Files.prototype.getReadStream = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<Stream> DownloadStreamAsync(string id, string versionId = null, TimeSpan? timeout = null)
  
public async Task<Uri> GetDownloadUriAsync(string id, string versionId = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     302 Found
Redirected to secured download at dl.boxcloud.com
Suggest Edits

Preflight Check

 

Authentication

 Authentication is required for this endpoint.
optionshttps://api.box.com/2.0/files/content

Body Params

name
string
required

The name of the file to be uploaded

parent
object
 
parent.id
string

Child of parent. The ID of the parent folder.

size
int32
required

The size of the file in bytes. Specify 0 for unknown file-sizes

The Pre-flight check API will verify that a file will be accepted by Box before you send all the bytes over the wire. It can be used for both first-time uploads, and uploading new versions of an existing File (on /files/[id]/content). If the call returns a 200, then you can proceed with a standard upload call. Preflight checks verify all permissions as if the file was actually uploaded including:

  • Folder upload permission
  • File name collisions
  • file size caps
  • folder and file name restrictions*
  • folder and account storage quota

A 200 response does not guarantee that your upload call will succeed. In practice, it has been shown to reduce failed uploads by more than 99%. Highly active folders, common filenames, and accounts near their quota limits may get a 200 for the preflight, and then have a real conflict during the actual upload. Error handling is key to making your application behave well for your users. Errors returned are the same as for file uploads.

Supported File Names:

Box only supports file names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with trailing spaces, and the special names “.” and “..”.

Returns

A 200 is returned if the upload would be successful. An error is thrown when any of the preflight conditions are not met.

curl https://api.box.com/2.0/files/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "Wolves owners.ppt", "parent": {"id": "1523432"}, "size": 15243}' \
-X OPTIONS
package com.box.sdk

public class BoxFolder

public void canUpload(String name, long fileSize)

public class BoxFile

public void canUploadVersion(String name, long fileSize, String parentID)
Files.prototype.preflightUploadFile = function(parentFolderID, fileData, qs, callback)

Files.prototype.preflightUploadNewFileVersion = function(fileID, fileData, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxPreflightCheck> PreflightCheck(BoxPreflightCheckRequest preflightCheckRequest)
  
public async Task<BoxPreflightCheck> PreflightCheckNewVersion(string fileId, BoxPreflightCheckRequest preflightCheckRequest)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Upload File

Use the Uploads API to allow users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error.

A different Box URL, https://upload.box.com/api/2.0/files/content, handles uploads. This API uses the multipart post method to complete all upload tasks. You can optionally specify a Content-MD5 header with the SHA1 hash of the file to ensure that the file is not corrupted in transit. Note: API Explorer will not work for this endpoint.

 

Authentication

 Authentication is required for this endpoint.
posthttps://upload.box.com/api/2.0/files/content

Body Params

attributes
object
required

File attributes

 
name
string
required

Name of the file. child of attributes

parent
object
required

Folder object being uploaded into. child of attributes

 
id
string
required

Child of parent. Designates folder_id of parent object. Use 0 for the root folder.

content_created_at
date-time

See content times for formatting

content_modified_at
date-time

When the content of this file was last modified

Headers

Content-MD5
string

The SHA1 hash of the file

Supported File Names:

Box only supports file names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with trailing spaces, and the special names “.” and “..”.

Upload Limits

Upload limits are dictated by the type of account you have. More information can be found here

Returns

A 201 will be received on successful upload. A full file object is returned inside of a collection if the ID is valid and if the update is successful. Additionally, an 409 error is thrown when a name collision occurs.

Note

Note that the file bytes should come after the JSON for best performance.

Name Collision

If you receive a name collision you can use the SHA-1 that is returned with the file to check if the existing file is identical to the one you are trying to upload.

curl https://upload.box.com/api/2.0/files/content \
  -H "Authorization: Bearer ACCESS_TOKEN" -X POST \
  -F attributes='{"name":"tigers.jpeg", "parent":{"id":"11446498"}}' \
  -F file=@myfile.jpg
package com.box.sdk

public class BoxFolder

public BoxFile.Info uploadFile(FileUploadParams uploadParams)
Files.prototype.uploadFile = function(parentFolderID, filename, content, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream, List<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true, Uri uploadUri = null)
  
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "5000948880",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
            "name": "tigers.jpeg",
            "description": "a picture of tigers",
            "size": 629644,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "11446498",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Pictures"
                    }
                ]
            },
            "created_at": "2012-12-12T10:55:30-08:00",
            "modified_at": "2012-12-12T11:04:26-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2013-02-04T16:57:52-08:00",
            "content_modified_at": "2013-02-04T16:57:52-08:00",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            },
            "item_status": "active"
        }
    ]
}
Suggest Edits

Delete File

Discards a file to the trash. The etag of the file can be included as an ‘If-Match’ header to prevent race conditions.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Headers

If-Match
string

The etag of the file. This is in the ‘etag’ field of the file object.

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

Returns

An empty 204 response is sent to confirm deletion of the file. If the If-Match header is sent and fails, a 412 Precondition Failed error is returned.

curl https://api.box.com/2.0/files/FILE_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "If-Match: a_unique_value" \
-X DELETE
package com.box.sdk

public class BoxFile

public void delete()
Files.prototype.delete = function(fileID, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<bool> DeleteAsync(string id, string etag=null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Upload File Version

Uploading a new file version is performed in the same way as uploading a file. This method is used to upload a new version of an existing file in a user’s account. Similar to regular file uploads, these are performed as multipart form uploads. An optional If-Match header can be included to prevent race conditions. The filename on Box will remain the same as the previous version. To update the file’s name, you can specify a new name for the file in the POST by setting the name field in the body.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0https://upload.box.com/api/2.0/files/file_id/content

Path Params

file_id
string
required

Body Params

name
string
content_modified_at
date-time

When the content of this file was last modified

Headers

If-Match
string

This is in the ‘etag’ field of the file object.

Note that uploads are handled through https://upload.box.com.

curl https://upload.box.com/api/2.0/files/FILE_ID/content \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "If-Match: ETAG_OF_ORIGINAL" \
-F filename=@FILE_NAME
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "5000948880",
      "sequence_id": "3",
      "etag": "3",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
      "name": "tigers.jpeg",
      "description": "a picture of tigers",
      "size": 629644,
      "path_collection": {
        "total_count": 2,
        "entries": [
          {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
          },
          {
            "type": "folder",
            "id": "11446498",
            "sequence_id": "1",
            "etag": "1",
            "name": "Pictures"
          }
        ]
      },
      "created_at": "2012-12-12T10:55:30-08:00",
      "modified_at": "2012-12-12T11:04:26-08:00",
      "trashed_at": null,
      "purged_at": null,
      "content_created_at": "2013-02-04T16:57:52-08:00",
      "content_modified_at": "2013-02-04T16:57:52-08:00",
      "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
          "can_download": true,
          "can_preview": true
        }
      },
      "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
      },
      "item_status": "active"
    }
  ]
}
Suggest Edits

View Versions

If there are previous versions of this file, this method can be used to retrieve information about the older versions.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/versions

Path Params

file_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

An array of version objects are returned. If there are no previous versions of this file, then an empty array will be returned.

curl https://api.box.com/2.0/files/FILE_ID/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
package com.box.sdk

public class BoxFile

public Collection<BoxFileVersion> getVersions()
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxCollection<BoxFileVersion>> ViewVersionsAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
 "total_count": 1,
 "entries": [
    {
     "type": "file_version",
     "id": "672259576",
     "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9",
     "name": "Dragons.js",
     "size": 92556,
     "created_at": "2012-08-20T10:20:30-07:00",
     "modified_at": "2012-11-28T13:14:58-08:00",
     "modified_by": {
       "type": "user",
       "id": "183732129",
       "name": "sean rose",
       "login": "sean+apitest@box.com"
     }
	 }
 ]
}
Suggest Edits

Download Version

 

Use version url parameter referenced in Download a File section

Suggest Edits

Promote Version

If there are previous versions of this file, this method can be used to promote one of the older versions to the top of the stack. This actually mints a copy of the old version and puts it on the top of the versions stack. The file will have the exact same contents, the same SHA1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/versions/current

Path Params

file_id
string
required

Body Params

type
string
required

Must be ‘file_version’ for this request

id
string
required

Child of type. The ID of the file_version that you want to make current

Alert:

Versions are only tracked for Box users with premium accounts.

Returns

The newly promoted file_version object is returned, along with a ‘201 Created’ status

curl https://api.box.com/2.0/files/FILE_ID/versions/current \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"type": "file_version", "id" : "FILE_VERSION_ID"}' \
-X POST
package com.box.sdk

public class BoxFileVersion

public void promote()
Not Supported
Not Supported
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "file_version",
    "id": "871399",
    "sha1": "12039d6dd9a7e6eefc78846802e",
    "name": "Stark Family Lineage.doc",
    "size": 11,
    "created_at": "2013-11-20T13:20:50-08:00",
    "modified_at": "2013-11-20T13:26:48-08:00",
    "modified_by": {
        "type": "user",
        "id": "13711334",
        "name": "Eddard Stark",
        "login": "ned@winterfell.com"
    }
}
Suggest Edits

Delete Old Version

Discards a specific file version to the trash.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id/versions/2.0_id

Path Params

file_id
string
required
version_id
string
required

Id of the file version

Headers

If-Match
string

The etag of the file. This is in the ‘etag’ field of the file object.

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

Returns

An empty 204 response is sent to confirm deletion of the file. If the If-Match header is sent and fails, a ‘412 Precondition Failed’ error is returned.

curl https://api.box.com/2.0/files/FILE_ID/versions/VERSION_ID  \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     204 No Content
No content
Suggest Edits

Copy File

Used to copy a file to another folder. The original version of the file will not be altered.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/copy

Path Params

file_id
string
required

Body Params

parent
object
required

Folder object representing the new location of the file

 
id
string
required

Child of parent. The ID of the destination folder

version
string

An optional file version id if you want to copy a specific file version

name
string

An optional new name for the file

Returns

A full file object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file-name collision occurs.

A 409 will be returned if the intended destination folder is the same, as this will cause a name collision.

curl https://api.box.com/2.0/files/FILE_ID/copy \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"parent": {"id" : FOLDER_ID}}' \
-X POST
package com.box.sdk

public class BoxFile

public BoxFile.Info copy(BoxFolder destination)
  
public BoxFile.Info copy(BoxFolder destination, String newName)
Files.prototype.copy = function(fileID, newParentID, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> CopyAsync(BoxFileRequest fileRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg",
    "description": "a picture of tigers",
    "size": 629644,
    "path_collection": {
        "total_count": 2,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            {
                "type": "folder",
                "id": "11446498",
                "sequence_id": "1",
                "etag": "1",
                "name": "Pictures"
            }
        ]
    },
    "created_at": "2012-12-12T10:55:30-08:00",
    "modified_at": "2012-12-12T11:04:26-08:00",
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/rh935iit6ewrmw0unyul",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "11446498",
        "sequence_id": "1",
        "etag": "1",
        "name": "Pictures"
    },
    "item_status": "active"
}
Suggest Edits

Get Thumbnail

Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32,
64x64, 128x128, and 256x256 can be returned in the .png format and sizes of 32x32, 94x94, 160x160, and 320x320 can be returned in the .jpg format. Thumbnails can be generated for the image and video file formats listed here.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/thumbnail.extension

Path Params

file_id
string
required

Query Params

min_height
int32

The minimum height of the thumbnail

min_width
int32

The minimum width of the thumbnail

max_height
int32

The maximum height of the thumbnail

max_width
int32

The maximum width of the thumbnail

Returns

Note:

Thumbnails are only available for images and video file formats. You can also specify min=max in order to guarantee the thumbnail size requested.

There are three success cases that your application needs to account for:

If the thumbnail isn’t available yet, a 202 Accepted HTTP status will be returned, including a Location header pointing to a placeholder graphic that can be used until the thumbnail is returned. A Retry-After header will also be returned, indicating the time in seconds after which the thumbnail will be available. Your application should only attempt to get the thumbnail again after Retry-After time.

If Box can’t generate a thumbnail for this file type, a 302 Found response will be returned, redirecting to a placeholder graphic in the requested size for this particular file type, e.g. this for a CSV file).

If the thumbnail is available, a 200 OK response will be returned with the contents of the thumbnail in the body

If Box is unable to generate a thumbnail for this particular file, a 404 Not Found response will be returned with a code of preview_cannot_be_generated. If there are any bad parameters sent in, a standard 400 Bad Request will be returned.

curl https://api.box.com/2.0/files/FILE_ID/thumbnail.png?min_height=256&min_width=256 \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFile

public byte[] getThumbnail(ThumbnailFileType fileType, int minWidth, int minHeight, int maxWidth, int maxHeight)
Files.prototype.getThumbnail = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<Stream> GetThumbnailAsync(string id, int? minHeight = null, int? minWidth = null, int? maxHeight = null, int? maxWidth = null, bool throttle = true, bool handleRetry = true)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
Contents of thumbnail
Suggest Edits

Get File Collaborations

Use this to get a list of all the collaborations on a file i.e. all of the users that have access to that file.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/collaborations

Path Params

file_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return in a page. The default is 100 and the max is 1000.

offset
int32

The item at which to begin the response

Returns

A collection of collaboration objects is returned. If there are no collaborations on this file, an empty collection will be returned.

curl https://api.box.com/2.0/files/FILE_ID/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "14176246",
            "created_by": {
                "type": "user",
                "id": "4276790",
                "name": "David Lee",
                "login": "david@box.com"
            },
            "created_at": "2011-11-29T12:56:35-08:00",
            "modified_at": "2012-09-11T15:12:32-07:00",
            "expires_at": null,
            "status": "accepted",
            "accessible_by": {
                "type": "user",
                "id": "755492",
                "name": "Simon Tan",
                "login": "simon@box.net"
            },
            "role": "editor",
            "acknowledged_at": "2011-11-29T12:59:40-08:00",
            "item": null
        }
    ]
}
Suggest Edits

Get Trashed File

Retrieves an item that has been moved to the trash.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/trash

Path Params

file_id
string
required

Returns

The full item will be returned, including information about when the it was moved to the trash. A 404 will be returned if the item is not in the trash.

curl https://api.box.com/2.0/files/FILE_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxTrash

public BoxFile.Info getFileInfo(String fileID)

public BoxFile.Info getFileInfo(String fileID, String... fields)
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> GetTrashedAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "2",
    "etag": "2",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-01-30T18:44:00-08:00",
    "trashed_at": "2013-02-07T10:49:34-08:00",
    "purged_at": "2013-03-09T10:49:34-08:00",
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-01-30T18:44:00-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": null,
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}
Suggest Edits

Permanently Delete

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id/trash

Path Params

file_id
string
required

Returns

An empty 204 No Content response will be returned upon successful deletion. A 404 will be returned if the item is not in the trash.

curl https://api.box.com/2.0/files/FILE_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
package com.box.sdk

public class BoxTrash

public void deleteFile(String fileID)
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<bool> PurgeTrashedAsync(string id)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Restore Item

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id

Path Params

file_id
string
required

Body Params

name
string

The new name for this item

parent
object

The new parent folder for this item

 
id
string

Child of parent. The id of the new parent folder

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Note:

Passing a parent parameter only changes the place the restored content goes when the original parent where the content previously lived has been deleted.

Errors

403

The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

404

The item is not in the trash

409

There is an item with the same name in the folder the item is being restored to

curl https://api.box.com/2.0/files/FILE_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"non-conflicting-name.jpg"}' \
-X POST
package com.box.sdk

public class BoxTrash

public BoxFile.Info restoreFile(String fileID)
  
public BoxFile.Info restoreFile(String fileID, String newName, String newParentID)
Not Supported
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxFile> RestoreTrashedAsync(BoxFileRequest fileRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "file",
    "id": "5859258256",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c",
    "name": "Screenshot_1_30_13_6_37_PM.png",
    "description": "",
    "size": 163265,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_at": "2013-01-30T18:43:56-08:00",
    "modified_at": "2013-02-07T10:56:58-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-30T18:43:56-08:00",
    "content_modified_at": "2013-02-07T10:56:58-08:00",
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": {
        "url": "https://seanrose.box.com/s/ebgti08mtmhbpb4vlp55",
        "download_url": "https://seanrose.box.com/shared/static/ebgti08mtmhbpb4vlp55.png",
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 4,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}
Suggest Edits

Get File's Comments

Retrieves the comments on a particular file, if any exist.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/comments

Path Params

file_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

Returns

A collection of comment objects are returned. If there are no comments on the file, an empty comments array is returned.

curl https://api.box.com/2.0/files/FILE_ID/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
package com.box.sdk

public class BoxFile

public List<BoxComment.Info> getComments()
Files.prototype.getComments = function(fileID, qs, callback)
namespace Box.V2.Managers
class BoxFilesManager

public async Task<BoxCollection<BoxComment>> GetCommentsAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 1,
    "entries": [
        {
            "type": "comment",
            "id": "191969",
            "is_reply_comment": false,
            "message": "These tigers are cool!",
            "created_by": {
                "type": "user",
                "id": "17738362",
                "name": "sean rose",
                "login": "sean@box.com"
            },
            "created_at": "2012-12-12T11:25:01-08:00",
            "item": {
                "id": "5000948880",
                "type": "file"
            },
            "modified_at": "2012-12-12T11:25:01-08:00"
        }
    ]
}
Suggest Edits

Get File's Tasks

Retrieves all of the tasks for given file.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/tasks

Path Params

file_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

Returns

A collection of mini task objects is returned. If there are no tasks, an empty collection will be returned.

curl https://api.box.com/2.0/files/FILE_ID/tasks \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFile

public List<BoxTask.Info> getTasks()
Not Supported
Not Supported
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 1,
    "entries": [
        {
            "type": "task",
            "id": "1786931",
            "item": {
                "type": "file",
                "id": "7026335894",
                "sequence_id": "6",
                "etag": "6",
                "sha1": "81cc829fb8366fcfc108aa6c5a9bde01a6a10c16",
                "name": "API - Persist On-Behalf-Of information.docx"
            },
            "due_at": null
        }
    ]
}
Suggest Edits

Folder Object

 

Folders contain information about the items contained inside of them, including files and other folders. There is also a set of metadata such as who owns the folder and when it was modified that is also returned. When accessing other resources that make reference to folders, a ‘mini folder’ object will be used. The 'mini folder' object will return type, id, sequence_id, etag, and name.

Italicized attributes are not returned by default and must be retrieved through the fields parameter.

type

string

For folders is ‘folder’

id

string

The folder’s ID.

sequence_id

string

A unique ID for use with the /events endpoint.

May be null for some folders such as root or trash.

etag

string

A unique string identifying the version of this folder.

May be null for some folders such as root or trash.

name

string

The name of the folder.

created_at

timestamp

The time the folder was created.

May be null for some folders such as root or trash.

description

string

The description of the folder.

size

integer

The folder size in bytes. Be careful parsing this integer, it can easily go into EE notation: see IEEE754 format.

path_collection

collection

The path of folders to this folder, starting at the root.

created_by

mini user object

The user who created this folder.

modified_by

mini user object

The user who last modified this folder.

trashed_at

timestamp

The time the folder or its contents were put in the trash.

May be null for some folders such as root or trash.

purged_at

timestamp

The time the folder or its contents will be purged from the trash.

May be null for some folders such as root or trash.

content_created_at

timestamp

The time the folder or its contents were originally created (according to the uploader).
May be null for some folders such as root or trash.

content_modified_at

timestamp

The time the folder or its contents were last modified (according to the uploader).

May be null for some folders such as root or trash.

owned_by

mini user object

The user who owns this folder.

shared_link

object

The shared link for this folder. Null if not set.

folder_upload_email

object

The upload email address for this folder. Null if not set.

parent

mini folder object

The folder that contains this one.
May be null for folders such as root, trash and child folders whose parent is inaccessible.

item_status

string

Whether this item is deleted or not.

item_collection

collection

A collection of mini file and folder objects contained in this folder.

sync_state

string

Whether this folder will be synced by the Box sync clients or not. Can be synced, not_synced, or partially_synced.

has_collaborations

boolean

Whether this folder has any collaborators.

permissions

object

The permissions that the current user has on this folder. The keys are can_download, can_upload, can_rename, can_delete, can_share, can_invite_collaborator, and can_set_share_access. Each value is a boolean.

tags

array of strings

All tags applied to this folder.

can_non_owners_invite

boolean

Whether non-owners can invite collaborators to this folder.

is_externally_owned

boolean

Whether this folder is owned by a user outside of the enterprise

allowed_shared_link_access_levels

array of strings

Access level settings for shared links set by administrator. Can include collaborators, open, and/or company.

allowed_invitee_roles

string

Folder collaboration collaboration settings allowed by the enterprise administrator.

watermark_info

object

Information about the watermark status of this folder. See Watermarking for additional endpoints.

Fields:
is_watermarked (boolean): Whether the folder is watermarked or not.

{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    },
    "tags": [
        "approved",
        "ready to publish"
    ]
}
{
    "type":"folder",
    "id":"301415432",
    "sequence_id":"0",
    "etag":"0",
    "name":"my first sub-folder"
}
Suggest Edits

Get Folder's Info

Retrieves the full information about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id “0”.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Returns

A full folder object is returned, including the most current information available about it. An 404 error is thrown if the folder does not exist or a 4xx if the user does not have access to it.

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
package com.box.sdk

public class BoxFolder

public BoxFolder.Info getInfo()
Folders.prototype.get = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> GetInformationAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}
Suggest Edits

Get Folder’s Items

Retrieves the files and/or folders contained within this folder without any other metadata about the folder. Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using the limit and offset parameters.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/items

Path Params

folder_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return in a page. The default is 100 and the max is 1000.

offset
string

The offset at which to begin the response. An offset of value of 0 will start at the beginning of the folder-listing. Note: If there are hidden items in your previous response, your next offset should be = offset + limit, not the # of records you received back. The default is 0.

Returns

A collection of items contained in the folder is returned. An error is thrown if the folder does not exist, or if any of the parameters are invalid. The total_count returned may not match the number of entries when using the enterprise scope, because external folders are excluded from the list of entries.

curl https://api.box.com/2.0/folders/FOLDER_ID/items?limit=2&offset=0 \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFolder

public Iterable<BoxItem.Info> getChildren(final String... fields)

public PartialCollection<BoxItem.Info> getChildrenRange(long offset, long limit, String... fields)

public Iterator<BoxItem.Info> iterator()
Folders.prototype.getItems = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxCollection<BoxItem>> GetFolderItemsAsync(string id, int limit, int offset = 0, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 24,
    "entries": [
        {
            "type": "folder",
            "id": "192429928",
            "sequence_id": "1",
            "etag": "1",
            "name": "Stephen Curry Three Pointers"
        },
        {
            "type": "file",
            "id": "818853862",
            "sequence_id": "0",
            "etag": "0",
            "name": "Warriors.jpg"
        }
    ],
    "offset": 0,
    "limit": 2,
    "order": [
        {
            "by": "type",
            "direction": "ASC"
        },
        {
            "by": "name",
            "direction": "ASC"
        }
    ]
}
Suggest Edits

Create Folder

Used to create a new empty folder. The new folder will be created inside of the specified parent folder

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders

Body Params

name
string
required

The desired name for the folder

parent
object
 
parent.id
string
required

Child of parent. The ID of the parent folder

Supported Folder Names:

Box only supports folder names of 255 characters or less. Names that will not be supported are those that contain non-printable ascii, / or \, names with trailing spaces, and the special names “.” and “..”.

Returns

A full folder object is returned if the parent folder ID is valid and if no name collisions occur.

curl https://api.box.com/2.0/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"New Folder", "parent": {"id": "0"}}' \
-X POST
package com.box.sdk

public class BoxFolder
  
public BoxFolder.Info createFolder(String name)
Folders.prototype.create = function(parentFolderID, name, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> CreateAsync(BoxFolderRequest folderRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 0,
        "entries": [],
        "offset": 0,
        "limit": 100
    }
}
Suggest Edits

Update Folder

Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update the folder_upload_email attribute. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Body Params

name
string

The name of the folder.

description
string

The description of the folder.

parent
object

The parent folder of this file.

 
id
string

Child of owned_by. The ID of the user, should be your own user ID.

shared_link
object

An object representing this item’s shared link and associated permissions.

 
access
string

Child of folder_upload_email. Can be open or collaborators.

unshared_at
date-time

Child of shared_link. The day that this link should be disabled at. RFC-3339 valid date-timestamps are rounded off to the given day.

permissions
object

Child of shared_link. The set of permissions that apply to this link.

 
can_download
boolean

Child of permissions. Whether this link allows downloads.

can_preview
boolean

Child of permissions. Whether this link allows previews.

folder_upload_email
object

The email-to-upload address for this folder. Set to “null” to disable or set access to "open" to enable.

 
owned_by
object

The user who owns the folder. Only used when moving a collaborated folder that you are not the owner of to a folder you are the owner of. Not a substitute for changing folder owners, please reference collaborations to accomplish folder ownership changes.

 
sync_state
string

Whether Box Sync clients will sync this folder. Values of synced or not_synced can be sent, while partially_synced may also be returned.

tags
array of strings

All tags attached to this folder. To add/remove a tag to/from a folder, you can first get the folder’s current tags (be sure to specify ?fields=tags, since the tags field is not returned by default); then modify the list as required; and finally, set the folder’s entire list of tags.

Headers

If-Match
string

This is in the ‘etag’ field of the folder object.

Returns

The updated folder is returned if the name is valid. Errors generally occur only if there is a name collision.

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"New Folder Name!"}' \
-X PUT
package com.box.sdk

public class BoxFolder
  
public void updateInfo(BoxFolder.Info info)
Folders.prototype.update = function(folderID, options, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> UpdateInformationAsync(BoxFolderRequest folderRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
   "type": "folder",
   "id": "11446498",
   "sequence_id": "1",
   "etag": "1",
   "name": "New Folder Name!",
   "created_at": "2012-12-12T10:53:43-08:00",
   "modified_at": "2012-12-12T11:15:04-08:00",
   "description": "Some pictures I took",
   "size": 629644,
 "path_collection": {
 	"total_count": 1,
 "entries": [
 {
   "type": "folder",
   "id": "0",
   "sequence_id": null,
   "etag": null,
   "name": "All Files"
 }
 ]
 },
 "created_by": {
   "type": "user",
   "id": "17738362",
   "name": "sean rose",
   "login": "sean@box.com"
 },
 "modified_by": {
   "type": "user",
   "id": "17738362",
   "name": "sean rose",
   "login": "sean@box.com"
 },
 "owned_by": {
   "type": "user",
   "id": "17738362",
   "name": "sean rose",
   "login": "sean@box.com"
 },
   "shared_link": {
   "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
   "download_url": null,
   "vanity_url": null,
   "is_password_enabled": false,
   "unshared_at": null,
   "download_count": 0,
   "preview_count": 0,
   "access": "open",
   "permissions": {
   "can_download": true,
   "can_preview": true
 }
 },
 "folder_upload_email": {
   "access": "open",
   "email": "upload.Picture.k13sdz1@u.box.com"
 },
 "parent": {
   "type": "folder",
   "id": "0",
   "sequence_id": null,
   "etag": null,
   "name": "All Files"
 },
 "item_status": "active",
 "item_collection": {
 	"total_count": 1,
 "entries": [
 {
   "type": "file",
   "id": "5000948880",
   "sequence_id": "3",
   "etag": "3",
   "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
   "name": "tigers.jpeg"
 }
 ],
 "offset": 0,
 "limit": 100
 }
}
Suggest Edits

Delete Folder

Used to delete a folder. A recursive parameter must be included in order to delete folders that have items inside of them. An optional If-Match header can be included to ensure that client only deletes the folder if it knows about the latest version.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Query Params

recursive
boolean

Whether to delete this folder if it has items inside of it.

Headers

If-Match
string

This is in the ‘etag’ field of the folder object.

Trash:

Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

Returns

An empty 204 response will be returned upon successful deletion. An error is thrown if the folder is not empty and the ‘recursive’ parameter is not included.

curl https://api.box.com/2.0/folders/FOLDER_ID?recursive=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
package com.box.sdk

public class BoxFolder

public void delete(boolean recursive)
Folders.prototype.delete = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<bool> DeleteAsync(string id, bool recursive = false)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Copy Folder

Used to create a copy of a folder in another folder. The original version of the folder will not be altered.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders/folder_id/copy

Path Params

folder_id
string
required

Body Params

parent
object
required

Object representing the new location of the folder.

 
id
string
required

Child of parent. The ID of the destination folder.

name
string

An optional new name for the folder.

Returns

A full folder object is returned if the ID is valid and if the update is successful. Errors can be thrown if the destination folder is invalid or if a file-name collision occurs. A 409 will be returned if the intended destination folder is the same, as this will cause a name collision.

curl https://api.box.com/2.0/folders/FOLDER_ID/copy \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"parent": {"id" : DESTINATION_FOLDER_ID}}' \
-X POST
package com.box.sdk

public class BoxFolder

public BoxFolder.Info copy(BoxFolder destination, String newName)
Folders.prototype.copy = function(folderID, newParentID, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> CopyAsync(BoxFolderRequest folderRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     202 Accepted
{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}
Suggest Edits

Get Folder Collaborations

Use this to get a list of all the collaborations on a folder i.e. all of the users that have access to that folder.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/collaborations

Path Params

folder_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return in a page. The default is 100 and the max is 1000.

offset
int32

The item at which to begin the response

Returns

A collection of collaboration objects is returned. If there are no collaborations on this folder, an empty collection will be returned.

curl https://api.box.com/2.0/folders/FOLDER_ID/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxFolder

public Collection<BoxCollaboration.Info> getCollaborations()
Folders.prototype.getCollaborations = function(folderID, qs, callback)
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxCollection<BoxCollaboration>> GetCollaborationsAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 1,
    "entries": [
        {
            "type": "collaboration",
            "id": "14176246",
            "created_by": {
                "type": "user",
                "id": "4276790",
                "name": "David Lee",
                "login": "david@box.com"
            },
            "created_at": "2011-11-29T12:56:35-08:00",
            "modified_at": "2012-09-11T15:12:32-07:00",
            "expires_at": null,
            "status": "accepted",
            "accessible_by": {
                "type": "user",
                "id": "755492",
                "name": "Simon Tan",
                "login": "simon@box.net"
            },
            "role": "editor",
            "acknowledged_at": "2011-11-29T12:59:40-08:00",
            "item": null
        }
    ]
}
Suggest Edits

Get Trashed Items

Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using the limit and offset parameters.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/trash/items

Query Params

fields
string

Attribute(s) to include in the response

limit
int32

The maximum number of items to return

offset
int32

The item at which to begin the response

fields:

‘id’ and ‘type’ are always returned for each item.

Returns

A collection of items contained in the trash is returned. An error is thrown if any of the parameters are invalid.

curl https://api.box.com/2.0/folders/trash/items?limit=2&offset=0 \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxTrash

public Iterator<BoxItem.Info> iterator()
Not Supported
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxCollection<BoxItem>> GetTrashItemsAsync(int limit, int offset = 0, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "total_count": 49542,
    "entries": [
        {
            "type": "file",
            "id": "2701979016",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "9d976863fc849f6061ecf9736710bd9c2bce488c",
            "name": "file Tue Jul 24 145436 2012KWPX5S.csv"
        },
        {
            "type": "file",
            "id": "2698211586",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "09b0e2e9760caf7448c702db34ea001f356f1197",
            "name": "file Tue Jul 24 010055 20129Z6GS3.csv"
        }
    ],
    "offset": 0,
    "limit": 2
}
Suggest Edits

Get Trashed Folder

Retrieves an folder that has been moved to the trash.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/trash

Path Params

folder_id
string
required

Query Params

fields
string

Attribute(s) to include in the response

Returns

The full folder will be returned, including information about when it was moved to the trash. A 404 will be returned if the folder is not in the trash.

Errors

404

The folder is not in the trash

curl https://api.box.com/2.0/folders/FOLDER_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN"
package com.box.sdk

public class BoxTrash

public BoxFolder.Info getFolderInfo(String folderID)
  
public BoxFolder.Info getFolderInfo(String folderID, String... fields)
Not Supported
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> GetTrashedFolderAsync(string id, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "1",
    "etag": "1",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-01-17T13:48:23-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "1",
                "sequence_id": null,
                "etag": null,
                "name": "Trash"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": "2013-02-07T12:53:32-08:00",
    "purged_at": "2013-03-09T12:53:32-08:00",
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-01-17T13:48:23-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "trashed"
}
Suggest Edits

Permanently Delete

Permanently deletes an folder that is in the trash. The item will no longer exist in Box. This action cannot be undone.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/folders/folder_id/trash

Path Params

folder_id
string
required

Returns

An empty 204 No Content response will be returned upon successful deletion. A 404 will be returned if the item is not in the trash.

curl https://api.box.com/2.0/folders/FOLDER_ID/trash \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
package com.box.sdk

public class BoxTrash

public void deleteFolder(String folderID)
Not Supported
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<bool> PurgeTrashedFolderAsync(string id)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     204 No Content
No content
Suggest Edits

Restore Folder

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders/folder_id

Path Params

folder_id
string
required

Body Params

name
string

The new name for this item

parent
object

The new parent folder for this item

 
id
string

Child of parent. The id of the new parent folder

Returns

The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.

Errors

403

The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash

405

The item is not in the trash

409

There is an item with the same name in the folder the item is being restored to

curl https://api.box.com/2.0/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name":"non-conflicting-name"}' \
-X POST
package com.box.sdk

public class BoxTrash

public BoxFolder.Info restoreFolder(String folderID)

public BoxFolder.Info restoreFolder(String folderID, String newName, String newParentID)
Not Supported
namespace Box.V2.Managers
class BoxFoldersManager

public async Task<BoxFolder> RestoreTrashedFolderAsync(BoxFolderRequest folderRequest, List<string> fields = null)
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "folder",
    "id": "588970022",
    "sequence_id": "2",
    "etag": "2",
    "name": "heloo world",
    "created_at": "2013-01-15T16:15:27-08:00",
    "modified_at": "2013-02-07T13:26:00-08:00",
    "description": "",
    "size": 0,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2013-01-15T16:15:27-08:00",
    "content_modified_at": "2013-02-07T13:26:00-08:00",
    "owned_by": {
        "type": "user",
        "id": "181757341",
        "name": "sean test",
        "login": "sean+test@box.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}
Suggest Edits

Searching for Content

The search endpoint provides a powerful way to find Box content. Use the parameters described in this section to control what you search for.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/search?query=SEARCH_QUERY

Query Params

query
string
required

The string to search for. Box matches the search string against object names, descriptions, text contents of files, and other data.

scope
string

The scope on which you want search. Can be user_content for a search limited to the current user or enterprise_content to search an entire enterprise. To enable the enterprise_content scope for an administrator, please contact us.

file_extensions
string

Limit searches to specific file extensions like pdf,png, or doc. The value can be a single file extension or a comma-delimited list of extensions. For example: png,md,pdf

created_at_range
date-time

The date when the item was created. Specify the date range using RFC3339 timestamps separated by a comma. For example: `2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00. Either the beginning date or the ending date may be empty, but the separating comma is required. For example, if you omit the beginning date, then the ending date must begin with a comma.

updated_at_range
date-time

The date when the item was last updated. Specify the date range using RFC3339 timestamps separated by a comma. For example: `2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00. Either the beginning date or the ending date may be empty, but the separating comma is required. For example, if you omit the beginning date, then the ending date must begin with a comma.

size_range
int32

Return only files within a stated size range. Specify the range in bytes with lower and upper bounds separated by a comma, like so:lower_bound_size,upper_bound_size, where 1MB is 1000000 bytes. You can specify only the lower bound if you end this parameter with a comma. You can specify only the upper bound by placing a comma at the beginning of the number.

owner_user_ids
string

Search for objects by owner. Requires a user ID or a set of comma-delimited user IDs, like so: user_id_1,user_id_2,...

ancestor_folder_ids
string

Search for the contents of specific folders (and folders within them). Requires a folder ID or a set of comma-delimited folder IDs, like so: folder_id_1,folder_id_2,....

content_types
string

Search for objects of specified content types. The types can be name, description, file_content, comments, or tags. Requires a content type or a set of comma-delimited content_types, like so: content_type_1,content_type_2,....

type
string

The type of objects you want to include in the search results. The type can be file, folder, or web_link.

trash_content
string

Controls whether to search in the trash. The value can be trashed_only or non_trashed_only. Searches without this parameter default to searching non_trashed_only.

mdfilters
string

Searches for objects with a specific metadata object association. The filters must be placed in a single JSON object in a JSON array (see the tab labeled "Search with metadata" in the Request example). NOTE: For searches with the mdfilters parameter, a query string is not required.

templateKey
string

A child value of the mdfilters parameter. The key name of the template you want to search for. Currently you can search only for one template at a time.

scope
string

A child value of the mdfilters parameter. Specifies the scope of the template searched for. Currently, the scopes enterprise and global are supported.

filters
string

Child of mdfilters. Keys and values of the template you want to search within. For floats and dates, you can include an (inclusive) upper bound parameter lt or (inclusive) lower bound parameter gt or both bounds. An example filter for a “contractExpiration” on or before 08-01-16 UTC would be listed as {"contractExpiration":{"lt":"2016-08-01T00:00:00Z"}}.

limit
int32

The number of search results to return. The default is 30 and the maximum is 200.

offset
int32

The search result at which to start the response. The default is 0.

Limit and offset

Both limit and offset must be included for either to be used. Offset must be a multiple of limit.

Note:

If an item is added to Box then it becomes accessible through the search endpoint after ten minutes.

Returns

A collection of search results is returned. If there are no matching search results, the entries array will be empty.

curl https://api.box.com/2.0/search?query=sales&file_extensions=pdf&updated_at_range=2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00 \
-H "Authorization: Bearer ACCESS_TOKEN"
##Request before URL Encoding

https://api.box.com/2.0/search?mdfilters=[{"templateKey":"marketingCollateral", "scope":"enterprise", "filters":{"documentType": "datasheet"}}]

##cURL Request after URL encoding

curl https://api.box.com/2.0/search?mdfilters=%5B%7B%22templateKey%22%3A%22marketingCollateral%22%2C%20%22scope%22%3A%22enterprise%22%2C%20%22filters%22%3A%7B%22documentType%22%3A%20%22datasheet%22%7D%7D%5D \
-H "Authorization: Bearer ACCESS_TOKEN" 
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200 200 200
{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "172245607",
            "sequence_id": "1",
            "etag": "1",
            "sha1": "f89d97c5eea0a68e2cec911s932eca34a52355d2",
            "name": "Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf",
            "description": "This is old and needs to be updated - but general themes still apply",
            "size": 408979,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "2150506",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Marketing Active Work"
                    }
		 ]
            },
            "created_at": "2014-05-17T12:59:45-07:00",
            "modified_at": "2014-05-17T13:00:20-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2014-05-17T12:58:58-07:00",
            "content_modified_at": "2014-05-17T12:58:58-07:00",
            "created_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "19551097",
                "name": "Ted Blosser",
                "login": "ted@box.com"
            },
            "shared_link": null,
            "parent": {
                        "type": "folder",
                        "id": "2150506",
                        "sequence_id": "1",
                        "etag": "1",
                        "name": "Marketing Active Work"
            },
            "item_status": "active"
        }
    ],
    "limit": 30,
    "offset": 0
}
{
    "total_count": 2,
    "entries": [
        {
            "type": "file",
            "id": "27201036412",
            "sequence_id": "0",
            "etag": "0",
            "sha1": "71402e9009892ceb7210558abbe720a8e068bd8a",
            "name": "boxdev.png",
            "description": "",
            "size": 6708,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    }
                ]
            },
            "created_at": "2015-03-08T20:34:51-07:00",
            "modified_at": "2015-03-08T20:34:51-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-03-08T14:41:58-07:00",
            "content_modified_at": "2015-03-08T14:41:58-07:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "575496314",
                "sequence_id": "3",
                "etag": "3",
                "name": "Marketing Materials"
            },
            "item_status": "active"
        },
        {
            "type": "file",
            "id": "26776387434",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "72d773345dbba9cfb012c4a889a4fc6840e59bfa",
            "name": "2014 Companies.xlsx",
            "description": "",
            "size": 91821,
            "path_collection": {
                "total_count": 3,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    },
                    {
                        "type": "folder",
                        "id": "606618154",
                        "sequence_id": "0",
                        "etag": "0",
                        "name": "West"
                    }
                ]
            },
            "created_at": "2015-02-26T22:20:44-08:00",
            "modified_at": "2015-02-26T22:23:15-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-02-06T16:38:26-08:00",
            "content_modified_at": "2015-02-06T16:38:26-08:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "606618154",
                "sequence_id": "0",
                "etag": "0",
                "name": "West"
            },
            "item_status": "active"
        }
    ],
    "limit": 30,
    "offset": 0
}
Suggest Edits

Metadata Object

 

Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of "clientNumber":"820183" and "clientName":"bioMedicalCorp".

Metadata can be used for many purposes. Enterprises may want to have a better way to organize their digital assets for their marketing teams or developers may want to provide advanced content functionality such as facilitating workflows or approvals. Metadata is also visible in the Box Web Application. To learn more, please visit the help documentation.

Object

$template

string

The key of the template. Together with "$parent" and "$scope", this forms a unique identifier for the metadata instance.

$scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

$parent

string

The object ID the metadata object belongs to. Currently, both file and folder objects are supported. Updating metadata does not directly affect the parent object, such as changing the modified_at field for a file/folder.

$version

integer

The version of the object. Starts at 0 and increases every time a user-defined property is modified.

$id

string

36 character UUID to identify the metadata object.

$type

string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

$typeVersion

integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

key(s)

string

Custom value(s) defined by the template. These values also have a corresponding display name that are viewable in applications like the Box web application. The total char limit for a template instance can not exceed 16384 char. Since the $ char is reserved for metadata service keys, custom values can not be prefixed with the $ char.

Suggest Edits

Metadata Templates

 

Templates

Metadata that belongs to a file or folder is grouped by templates. 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. For example, a marketingCollateral template may define where and when specific marketing content should be used. You can also see the representation of the template in the Box web application while navigating to a file preview. Currently, metadata associated with folders does not show in the Box web application.

Each file can have multiple distinct template instances associated with it, such as a marketingCollateral and retentionPolicy template instances. Template instances are also grouped by scopes. Currently, the only scopes supported are enterprise and global. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. Attribute order within template instances is not guaranteed.

Currently, there are four attributes supported by templates: string, enum, float, and date (RFC 3339).

Metadata templates can be set up in the Admin Console.

Template Object

template

string

A unique identifier for the template. The identifier must be unique across the scope of the enterprise to which the metadata template is being applied. The character limit is 64 and is validated by this regex: ^[a-zA-Z][-a-zA-Z0-9]*$

scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

displayName

string

The display name of the template. The character limit is 4096.

hidden

boolean

Whether this template is hidden in the UI

fields

Collection
Template Field objects

The ordered set of key:value pairs for the template.

Template Fields Object

type

string

The data type of the field's value. Currently, there are four attributes supported by templates: "string", "enum", "float", and "date" (RFC 3339).

key

string

A unique identifier for the field. The identifier must be unique within the template to which it belongs. The character limit is 256. All characters are allowed.

displayName

string

The display name of the field. The character limit is 4096. All characters are allowed.

description

string

A description of the field. The character limit is 4096. All characters are allowed.

hidden

boolean

Whether this template is hidden in the UI

options

array of strings

For type "enum", a list of all possible values.

key

string

Child of options. For type "enum", one of the potential values. The character limit is 4096.

Global Properties Template

In addition to enterprise scoped templates, every file on Box has access to the global properties template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure.

Properties follow all the conventions of standard templates, except for being located at a different endpoint. All requests made to the properties template must be made to /files/{file_id}/metadata/global/properties.

Suggest Edits

Create Metadata Template

Used to create a new metadata template with the specified schema.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/metadata_templates/schema

Body Params

scope
string
required

The scope of the object. Only the enterprise scope is currently supported.

templateKey
string

A unique identifier for the template. The identifier must be unique across the scope of the enterprise to which the metadata template is being applied to. Defaults to a string derived from the displayName if no value is provided.

displayName
string
required

Child of fields. The display name of the field.

hidden
boolean

Whether this template is hidden in the UI. Defaults to false.

fields
array

The ordered set of key:value pairs for the template.

type
string
required

Child of fields. The data type of the field's value. Currently, there are four attributes supported by templates: string, enum, float, and date (RFC 3339).

key
string
required

Child of options. For type "enum", one of the potential values.

options
array

Child of fields. For type "enum", a list of all possible values.

Template Delete Not Supported

Once created, a template cannot be deleted. In order to hide the template from the UI, set the "hidden" flag to true. The template will still appear in the API.

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Returns

A 201 will be received on successful creation. The schema representing the metadata template created.

Errors

400

Request body contains invalid metadata schema.

403

Request body contains a scope that the user is not allowed to create a template for.

curl https://api.box.com/2.0/metadata_templates/schema \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "templateKey": "customer",
  "scope": "enterprise",
  "displayName": "Customer",
  "fields": [
    {
      "type": "string",
      "key": "customerTeam",
      "displayName": "Customer team"
    },
    {
      "type": "string",
      "key": "category",
      "displayName": "Category"
    },
    {
      "type": "string",
      "key": "brand",
      "displayName": "Brand"
    },
    {
      "type": "enum",
      "key": "fy",
      "displayName": "FY",
      "options": [
        {"key": "FY11"},
        {"key": "FY12"},
        {"key": "FY13"},
        {"key": "FY14"},
        {"key": "FY15"}
    ]},
    {
      "type": "enum",
      "key": "qtr",
      "displayName": "Qtr",
      "options": [
        {"key": "First"},
        {"key": "Second"},
        {"key": "Third"},
        {"key": "Fourth"}
    ]}
  ]}' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200 400 400403
{
    "templateKey": "customer",
    "scope": "enterprise_490685",
    "displayName": "Customer",
    "fields": [
        {
            "type": "string",
            "key": "customerTeam",
            "displayName": "Customer team",
            "hidden": false
        },
        {
            "type": "string",
            "key": "category",
            "displayName": "Category",
            "hidden": false
        },
        {
            "type": "string",
            "key": "brand",
            "displayName": "Brand",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "fy",
            "displayName": "FY",
            "options": [
                {
                    "key": "FY11"
                },
                {
                    "key": "FY12"
                },
                {
                    "key": "FY13"
                },
                {
                    "key": "FY14"
                },
                {
                    "key": "FY15"
                }
            ],
            "hidden": false
        },
        {
            "type": "enum",
            "key": "qtr",
            "displayName": "Qtr",
            "options": [
                {
                    "key": "First"
                },
                {
                    "key": "Second"
                },
                {
                    "key": "Third"
                },
                {
                    "key": "Fourth"
                }
            ],
            "hidden": false
        }
    ]
}
{
    "type": "error",
    "status": 400,
    "code": "bad_request",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "\"displayName\" is required and not set",
    "request_id": "616776114571858dc4ab8f"
}
{
    "type": "error",
    "status": 403,
    "code": "forbidden",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Forbidden",
    "request_id": "616776114571858dc4ab8f"
}
Suggest Edits

Get Metadata Template

Used to retrieve the schema for a given metadata template.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/metadata_templates/scope/template/schema

Path Params

scope
string
required
template
string
required

RETURNS

The schema representing the metadata template queried

curl https://api.box.com/2.0/metadata_templates/enterprise/productInfo/schema \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "templateKey": "productInfo",
    "scope": "enterprise_12345",
    "displayName": "Product Info",
    "hidden": false,
    "fields": [
        {
            "type": "float",
            "key": "skuNumber",
            "displayName": "SKU Number",
            "hidden": false
        },
        {
            "type": "string",
            "key": "description",
            "displayName": "Description",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "department",
            "displayName": "Department",
            "hidden": false,
            "options": [
                {
                    "key": "Beauty"
                },
                {
                    "key": "Shoes"
                },
                {
                    "key": "Accessories"
                },
                {
                    "key": "Clothing"
                },
                {
                    "key": "Handbags"
                },
                {
                    "key": "Bedding"
                },
                {
                    "key": "Watches"
                }
            ]
        },
        {
            "type": "date",
            "key": "displayDate",
            "displayName": "Display Date",
            "hidden": false
        }
    ]
}
Suggest Edits

Update Metadata Template

Used to update the schema of an existing template.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/metadata_templates/scope/template/schema

Path Params

scope
string
required
template
string
required

Body Params

op
string
required

The operation name. The list of possible operations is detailed below.

data
object

The data for the operation. Can vary depending on the operation.

 
fieldKey
string

For operations that affect a specific field, the key of the field to be affected.

fieldKeys
array of strings

For operations that affect multiple fields, the keys of the fields to be affected.

enumOptionKeys
array of strings

For operations that affect multiple enum options, the keys of the enum options to be affected.

Only Non-Breaking Changes Supported

This API only supports non-breaking changes (listed below). A non-breaking change is a change that does not affect the values of existing metadata instances. To hide a template or a field from the UI, set the "hidden" flag to true at the template or field level. The template or field will still appear in the API.

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Possible Template Operations:

  • addEnumOption: Adds an enum option at the end of the enum option list for the specified field
    Params:
    data: JSON object of the enum option to be added
    fieldKey: The key of the field to add the enum option. Must refer to an enum field
    Example: {"op":"addEnumOption","fieldKey":"category","data":{"key":"Technology"}}. This will add a new enum option Technology under the field category.

  • addField: Adds a field at the end of the field list for the template
    Params:
    data: JSON object of the field to be added.
    Example: {"op":"addField","data":{"displayName":"Category","key":"category","hidden":false,"type":"string"}}. This will add a new non-hidden string field with a displayName and key of category.

  • editField: Edits any number of the base properties of a field: displayName, hidden, description
    Params:
    data: JSON object of the properties to be changed and their new values.
    fieldKey: The key of the field to be edited
    Example: {"op":"editField","fieldKey":"category","data":{"displayName":"Customer Group"}}. This will update the field category to have a new display name of Customer Group.

  • editTemplate: Edits any number of the base properties of a template: displayName, hidden
    Params:
    data: JSON object of the properties to be changed and their new values.
    Example: {"op":"editTemplate","data":{"displayName":"Client"}}. This will update the template to have a new display name of Client.

  • reorderEnumOptions: Reorders the enum option list to match the requested enum option list
    Params:
    fieldKey: The key of the field to reorder enum options. Must refer to an enum field.
    enumOptionKeys: The new list of enum option keys in the requested order
    Example: {"op":"reorderEnumOptions","fieldKey":"category","enumOptionKeys":["option2","option1","option3"]}. This will reorder the enum options for field category to have option2 first, followed by option1, then option3.

  • reorderFields: Reorders the field list to match the requested field list
    Params:
    fieldKeys: The new list of field keys in the requested order
    Example: {"op":"reorderFields","fieldKeys":["field2","field1","field3"]}. This will reorder the fields for the template to have field2 first, followed by field1, then field3.

Returns

The schema representing the updated metadata template.

Error code

400

Request body contains invalid metadata schema.

403

Request body contains a scope that the user is not allowed to create templates for.

404

Requested template is not found.

curl https://api.box.com/2.0/metadata_templates/enterprise/customer/schema \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-d '[{"op":"editField","fieldKey":"category","data":{"displayName":"Customer Group"}}]' \
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200 400 400403
{
    "templateKey": "customer",
    "scope": "enterprise_490685",
    "displayName": "Customer",
    "fields": [
        {
            "type": "string",
            "key": "customerTeam",
            "displayName": "Customer team",
            "hidden": false
        },
        {
            "type": "string",
            "key": "category",
            "displayName": "Customer Group",
            "hidden": false
        },
        {
            "type": "string",
            "key": "brand",
            "displayName": "Brand",
            "hidden": false
        },
        {
            "type": "enum",
            "key": "fy",
            "displayName": "FY",
            "options": [
                {
                    "key": "FY11"
                },
                {
                    "key": "FY12"
                },
                {
                    "key": "FY13"
                },
                {
                    "key": "FY14"
                },
                {
                    "key": "FY15"
                }
            ],
            "hidden": false
        },
        {
            "type": "enum",
            "key": "qtr",
            "displayName": "Qtr",
            "options": [
                {
                    "key": "First"
                },
                {
                    "key": "Second"
                },
                {
                    "key": "Third"
                },
                {
                    "key": "Fourth"
                }
            ],
            "hidden": false
        }
    ]
}
{
    "type": "error",
    "status": 400,
    "code": "bad_request",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "\"displayName\" is required and not set",
    "request_id": "616776114571858dc4ab8f"
}
{
    "type": "error",
    "status": 403,
    "code": "forbidden",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "Forbidden",
    "request_id": "616776114571858dc4ab8f"
}
Suggest Edits

Get Enterprise Metadata

Used to retrieve all metadata templates within a user's enterprise. Currently only the enterprise scope is supported.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/metadata_templates/scope

Path Params

scope
string
required

Returns

All the templates within an enterprise and their corresponding schema

curl https://api.box.com/2.0/metadata_templates/enterprise \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "limit": 100,
    "entries": [
        {
            "templateKey": "documentFlow",
            "scope": "enterprise_12345",
            "displayName": "Document Flow",
            "hidden": false,
            "fields": [
                {
                    "type": "string",
                    "key": "currentDocumentStage",
                    "displayName": "Current Document Stage",
                    "hidden": false,
                    "description": "What stage in the process the document is in"
                },
                {
                    "type": "string",
                    "key": "needsApprovalFrom",
                    "displayName": "Needs Approval From",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "nextDocumentStage",
                    "displayName": "Next Document Stage",
                    "hidden": false,
                    "description": "Next document stage after approval is given"
                },
                {
                    "type": "float",
                    "key": "maximumDaysAllowedInCurrentStage",
                    "displayName": "Maximum Days Allowed In Current Stage",
                    "hidden": false,
                    "description": "Maximum number of days that the document is allowed to be in this stage."
                }
            ]
        },
        {
            "templateKey": "marketingCollateral",
            "scope": "enterprise_12345",
            "displayName": "Marketing Collateral",
            "hidden": false,
            "fields": [
                {
                    "type": "string",
                    "key": "audience1",
                    "displayName": "Audience",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "documentType",
                    "displayName": "Document Type",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "competitiveDocument",
                    "displayName": "Competitive Document",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "status",
                    "displayName": "Status",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "author",
                    "displayName": "Author",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "editor",
                    "displayName": "Editor",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "currentState",
                    "displayName": "Current State",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "previousState",
                    "displayName": "Previous State",
                    "hidden": false
                }
            ]
        },
        {
            "templateKey": "productInfo",
            "scope": "enterprise_12345",
            "displayName": "Product Info",
            "hidden": false,
            "fields": [
                {
                    "type": "float",
                    "key": "skuNumber",
                    "displayName": "SKU Number",
                    "hidden": false
                },
                {
                    "type": "string",
                    "key": "description",
                    "displayName": "Description",
                    "hidden": false
                },
                {
                    "type": "enum",
                    "key": "department",
                    "displayName": "Department",
                    "hidden": false,
                    "options": [
                        {
                            "key": "Beauty"
                        },
                        {
                            "key": "Shoes"
                        },
                        {
                            "key": "Accessories"
                        },
                        {
                            "key": "Clothing"
                        },
                        {
                            "key": "Handbags"
                        },
                        {
                            "key": "Bedding"
                        },
                        {
                            "key": "Watches"
                        }
                    ]
                },
                {
                    "type": "date",
                    "key": "displayDate",
                    "displayName": "Display Date",
                    "hidden": false
                }
            ]
        }
    ],
    "next_marker": null,
    "prev_marker": null
}
Suggest Edits

Metadata on Files and Folders

 

Template Instance Object

$template

string

The key of the template. Together with "$parent" and "$scope", this forms a unique identifier for the metadata instance.

$scope

string

The scope of the object. Global and enterprise scopes are currently supported. The Global scope represent the properties template currently, while the enterprise scope pertains to custom template within the enterprise. The id of the enterprise will be appended to the enterprise scope in this format: {scope}_{ENTERPRISE_ID}

$parent

string

The object ID the metadata object belongs to. Currently, both file and folder objects are supported. Updating metadata does not directly affect the parent object, such as changing the modified_at field for a file/folder.

$version

integer

The version of the object. Starts at 0 and increases every time a user-defined property is modified.

$id

string

36 character UUID to identify the metadata object.

$type

string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

$typeVersion

integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

key(s)

string

Custom value(s) defined by the template. These values also have a corresponding display name that are viewable in applications like the Box web application. The total char limit for a template instance can not exceed 16384 char. Since the $ char is reserved for metadata service keys, custom values can not be prefixed with the $ char.

Suggest Edits

Create Metadata on File

Used to create the metadata template instance for a corresponding Box file. When creating metadata, only values that adhere to the metadata template schema will be accepted.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required
template
string
required

Body Params

custom-defined-key(s)
string
required

Custom value(s) defined by a user or application

Headers

Content-Type
string
required

Must be application/json

Returns

An instance of the template that includes key:value pairs defined by a user or application. If the template instance already exists, a 409 HTTP status code of conflict will be returned and the update method should be used.

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "audience1": "internal", "documentType": "Q1 plans", "competitiveDocument": "no", "status": "active", "author": "Jones", "currentState": "proposal"}' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "competitiveDocument": "no",
    "status": "active",
    "author": "Jones",
    "currentState": "proposal",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}
Suggest Edits

Get Metadata on File

Used to retrieve the metadata template instance for a corresponding Box file.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required
template
string
required

Returns

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned.

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/bandInfo \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "competitiveDocument": "no",
    "status": "active",
    "author": "Jones",
    "currentState": "proposal",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}
Suggest Edits

Update Metadata on File

Used to update the template instance. The request body must follow the JSON-Patch specification, which is represented as a JSON array of operation objects (see examples for more details). Updates can be either add, replace, remove , test, move, or copy. The template instance can only be updated if the template instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the update operations, the metadata instance remains unchanged.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required
template
string
required

Body Params

op
string
required

The operation type. Must be add, replace, remove , test, move, or copy.

path
string
required

The path that designates the key, in the format of a JSON-Pointer. Since all keys are located at the root of the metadata instance, the key must be prefixed with a /. Special characters ~ and / in the key must be escaped according to JSON-Pointer specification. The value at the path must exist for the operation to be successful.

value
string

The value to be set or tested. Required for add, replace, and test operations. For add, if value already exists, then previous value will be overwritten by the new value. For replace, the metadata value must exist before replacing.For test, the value of the existing metadata instance must match the specified value.

from
string

Required for move or copy. The path that designates the source key, in the format of a JSON-Pointer, formatted in the same way as path. Used in conjunction with path: from specifies the source, path specifies the destination.

Headers

Content-Type
string
required

Must be application/json-patch+json

Returns

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path": "/competitiveDocument", "value": "no"},
{"op": "remove", "path": "/competitiveDocument"},
{"op": "test", "path": "/status", "value": "active"},
{"op": "replace", "path": "/status", "value": "inactive"},
{"op": "test", "path":"/author", "value":"Jones"},
{"op": "copy", "from":"/author", "path":"/editor"},
{"op": "test", "path":"/currentState", "value":"proposal"},
{"op": "move", "from":"/currentState", "path": "/previousState"},
{"op": "add", "path":"/currentState", "value": "reviewed"}]' \
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "audience1": "internal",
    "documentType": "Q1 plans",
    "status": "inactive",
    "author": "Jones",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 1,
    "$typeVersion": 0,
    "editor": "Jones",
    "previousState": "proposal",
    "currentState": "reviewed",
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
}
Suggest Edits

Delete Metadata on File

Used to delete the template instance. To delete custom key:value pairs within a template instance, you should refer to the updating metadata section.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/files/file_id/metadata/scope/template

Path Params

file_id
string
required
scope
string
required
template
string
required

Returns

An empty HTTP 204 response to confirm the deletion of the template instance.

curl https://api.box.com/2.0/files/5010739061/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Get all Metadata on File

Used to retrieve all metadata associated with a given file

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/files/file_id/metadata/

Path Params

file_id
string
required

Returns

An array of metadata instances associated with the file.

curl https://api.box.com/2.0/files/5010739061/metadata \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
    200
{
    "entries": [
        {
            "currentDocumentStage": "Init",
            "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
            "$parent": "file_5010739061",
            "$id": "50ba0dba-0f89-4395-b867-3e057c1f6ed9",
            "$version": 4,
            "$typeVersion": 2,
            "needsApprovalFrom": "Smith",
            "$template": "documentFlow",
            "$scope": "enterprise_12345"
        },
        {
            "$type": "productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9",
            "$parent": "file_5010739061",
            "$id": "15d1014a-06c2-47ad-9916-014eab456194",
            "$version": 2,
            "$typeVersion": 1,
            "skuNumber": 45334223,
            "description": "Watch",
            "$template": "productInfo",
            "$scope": "enterprise_12345"
        },
        {
            "Popularity": "25",
            "$type": "properties",
            "$parent": "file_5010739061",
            "$id": "b6f36cbc-fc7a-4eda-8889-130f350cc057",
            "$version": 0,
            "$typeVersion": 2,
            "$template": "properties",
            "$scope": "global"
        },

    ],
    "limit": 100
}
Suggest Edits

Create Metadata on Folder

Used to create the metadata template instance for a corresponding Box folder. When creating metadata, only values that adhere to the metadata template schema will be accepted.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/folders/folder_id/metadata/scope/template

Path Params

folder_id
string
required
scope
string
required
template
string
required

Body Params

JSON formatted metadata value(s)
string
required

JSON formatted value(s) for the specific metadata template

Headers

Content-Type
string
required

Must be application/json

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If the template instance already exists, a 409 HTTP status code of conflict will be returned and the update method should be used.

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currentDocumentStage": "initial vetting", "needsApprovalFrom": "vetting team", "nextDocumentStage": "prioritization"}' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}
Suggest Edits

Get Metadata on Folder

Used to retrieve the metadata template instance for a corresponding Box folder.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/metadata/scope/template

Path Params

folder_id
string
required
scope
string
required
template
string
required

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned.

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "currentDocumentStage": "initial vetting",
    "needsApprovalFrom": "vetting team",
    "nextDocumentStage": "prioritization",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 0,
    "$typeVersion": 2,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}
Suggest Edits

Update Metadata on Folder

Used to update the template instance. Updates can be either add, replace, remove , or test. The template instance can only be updated if the template instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/folders/folder_id/metadata/scope/template

Path Params

folder_id
string
required
scope
string
required
template
string
required

Body Params

op
string
required

The operation type. Must be add, replace, remove , or test.

path
string
required

The path that designates the key. Must be prefixed with a /

value
string

The value to be set. If value already exists, then previous value will be overwritten by the new value. Required for add and replace operations.

Headers

Content-Type
string
required

Must be application/json-patch+json

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An instance of the template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path":"/currentDocumentStage", "value": "initial vetting" },
	{"op": "replace", "path":"/currentDocumentStage", "value": "prioritization" },
  {"op": "test", "path":"/needsApprovalFrom", "value": "vetting team" },
  {"op": "replace", "path":"/needsApprovalFrom", "value": "planning team" },
	{"op": "add", "path":"/maximumDaysAllowedInCurrentStage", "value": 5},
  {"op": "test", "path":"/nextDocumentStage", "value": "prioritization" },
	{"op": "remove", "path":"/nextDocumentStage"}]' \
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "currentDocumentStage": "prioritization",
    "needsApprovalFrom": "planning team",
    "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
    "$parent": "folder_998951261",
    "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
    "$version": 1,
    "$typeVersion": 2,
    "maximumDaysAllowedInCurrentStage": 5,
    "$template": "documentFlow",
    "$scope": "enterprise_12345"
}
Suggest Edits

Delete Metadata on Folder

Used to delete the template instance. To delete custom key:value pairs within a template instance, you should refer to the updating metadata section.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/folders/folder_id/metadata/scope/template

Path Params

folder_id
string
required
scope
string
required
template
string
required

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.
If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An empty HTTP 204 response to confirm the deletion of the template instance.

curl https://api.box.com/2.0/folders/998951261/metadata/enterprise/documentFlow \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Get All Metadata on Folder

Used to retrieve all metadata associated with a given folder

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/folders/folder_id/metadata

Path Params

folder_id
string
required

Returns

Available in Beta

As with any Beta, you may encounter issues with functionality. Box reserves the right to make changes which may improve, impair, add or remove functionality with these APIs.

If you would like to provide any feedback, please email metadata-feedback@box.com. We would love to hear from you.

Folder metadata operations on folder ID 0 (zero) are not allowed.

Attempts to perform Folder metadata operations on folder ID 0 (zero) will result in a 403 HTTP status code.

An array of metadata instances associated with the folder.

curl https://api.box.com/2.0/folders/998951261/metadata \
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
    200
{
    "entries": [
        {
            "currentDocumentStage": "prioritization",
            "needsApprovalFrom": "planning team",
            "$type": "documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f",
            "$parent": "folder_998951261",
            "$id": "e57f90ff-0044-48c2-807d-06b908765baf",
            "$version": 1,
            "$typeVersion": 2,
            "maximumDaysAllowedInCurrentStage": 5,
            "$template": "documentFlow",
            "$scope": "enterprise_12345"
        },
        {
            "skuNumber": 45234522115075,
            "description": "Hat",
            "department": "Accessories",
            "$type": "productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9",
            "$parent": "folder_998951261",
            "$id": "0dd54220-8340-4ea1-bd3f-59a23c68ccdd",
            "$version": 0,
            "$typeVersion": 1,
            "$template": "productInfo",
            "$scope": "enterprise_12345"
        }
    ],
    "limit": 100
}
Suggest Edits

User Object

 

The users endpoint is used for managing a user and its content. For an individual user, this includes their own user information and content. For an enterprise admin, this includes both the individual user and any other users in the admin’s enterprise account. Italicized attributes are not returned by default and must be retrieved through the fields parameter.

type

string

For users is ‘user’.

id

string

A unique string identifying this user.

name

string

The name of this user.

login

string

The email address this user uses to login.

created_at

timestamp

The time this user was created.

modified_at

timestamp

The time this user was last modified.

The language of this user.

The timezone of this user.

space_amount

integer

The user’s total available space amount in bytes.

space_used

integer

The amount of space in use by the user.

max_upload_size

integer

The maximum individual file size in bytes this user can have.

status

string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

job_title

string

The user’s job title.

phone

string

The user’s phone number.

address

string

The user’s address.

avatar_url

string

URL of this user’s avatar image.

role

string

This user’s enterprise role. Can be admin, coadmin, or user.

tracking_codes

array

An array of key/value pairs set by the user’s admin.

can_see_managed_users

boolean

Whether this user can see other enterprise users in her contact list.

is_sync_enabled

boolean

Whether or not this user can use Box Sync.

is_external_collab_restricted

boolean

Whether this user is allowed to collaborate with users outside her enterprise.

is_exempt_from_device_limits
boolean

Whether to exempt this user from Enterprise device limits.

is_exempt_from_login_verification

boolean

Whether or not this user must use two-factor authentication.

enterprise

object

Mini representation of this user’s enterprise, including the ID of its enterprise.

my_tags

array of strings

Tags for all files and folders owned by this user.

hostname

string

The root (protocol, subdomain, domain) of any links that need to be generated for this user

is_platform_access_only

boolean

Specifies if a user is an App User. If the value is true, the user is an App User.

{
    "type": "user",
    "id": "181216415",
    "name": "sean rose",
    "login": "sean+awesome@box.com",
    "created_at": "2012-05-03T21:39:11-07:00",
    "modified_at": "2012-11-14T11:21:32-08:00",
    "role": "admin",
    "language": "en",
    "timezone": "Africa/Bujumbura",
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "max_upload_size": 2147483648,
    "tracking_codes": [],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "6509241374",
    "address": "",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false,
    "enterprise": {
        "type": "enterprise",
        "id": "17077211",
        "name": "seanrose enterprise"
    },
    "my_tags": [
        "important",
        "needs review"
    ]
}
{
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
}
Suggest Edits

Create User

Used to provision a new Managed User in an enterprise. This method only works for enterprise admins.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/users

Body Params

login
string
required

The email address this user uses to login

name
string
required

The name of this user

role
string

This user’s enterprise role. Can be coadmin or user

language
string

The language of this user. Input format follows ISO 639-1 language code format.

is_sync_enabled
boolean

Whether or not this user can use Box Sync

job_title
string

The user’s job title

phone
string

The user’s phone number

address
string

The user’s address

space_amount
int32

The user’s total available space amount in bytes

tracking_codes
array of mixed types

An array of key/value pairs set by the user’s admin

can_see_managed_users
boolean

Whether or not user can see other managed users

timezone
string

The user's timezone. Input format follows tz database timezones.

is_exempt_from_device_limits
boolean

Whether to exempt this user from Enterprise device limits

is_exempt_from_login_verification
boolean

Whether or not this user must use two-factor authentication

is_external_collab_restricted
boolean

Whether or not the user is restricted from external collaborations

status
string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

Returns

Returns the standard user object for a newly created user when making the request with just the required parameters.

Errors may be thrown when the fields are invalid or this API call is made from a non-admin account.

curl https://api.box.com/2.0/users \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"login": "eddard@box.com", "name": "Ned Stark"}' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 Created
{
    "type": "user",
    "id": "187273718",
    "name": "Ned Stark",
    "login": "eddard@box.com",
    "created_at": "2012-11-15T16:34:28-08:00",
    "modified_at": "2012-11-15T16:34:29-08:00",
    "role": "user",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 2147483648,
    "status": "active",
    "job_title": "",
    "phone": "555-555-5555",
    "address": "555 Box Lane",
    "avatar_url": "https://www.box.com/api/avatar/large/187273718"
}
Suggest Edits

Create App User

Used to provision a new App User in an enterprise. This method only works for service accounts.

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. For more information about users, please visit this page.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/users

Body Params

name
string
required

The name of this user

is_platform_access_only
boolean
required

Specifies that an App User is created. Value must be "true".

language
string

The language of the user. Input format follows ISO 639-1 language code format.

job_title
string

The user's job title

timezone
string

The user's timezone. Input format follows tz database timezones.

phone
string

The user's phone number.

address
string

The user's address.

space_amount
int32

The user’s total available space amount in bytes.

status
string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

is_external_collab_restricted
boolean

Whether or not the user is restricted from external collaborations.

can_see_managed_users
boolean

Whether or not user can see managed users

Returns

Returns the user object for the newly created App User. Errors may be thrown when the fields are invalid or this API call is made from a non-admin account.

curl https://api.box.com/2.0/users \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "Ned Stark", "is_platform_access_only": true}' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     201 201
{
    "type": "user",
    "id": "236506102",
    "name": "Ned Stark",
    "login": "AppUser_59659_vuNs7OCQ7y@box.com",
    "created_at": "2015-04-20T20:09:59-07:00",
    "modified_at": "2015-04-20T20:09:59-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 16106127360,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": ""
}
Suggest Edits

Get Current User

Retrieves information about the user who is currently logged in i.e. the user for whom this auth token was generated.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/users/me

Returns

Returns a single complete user object.

curl https://api.box.com/2.0/users/me
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "type": "user",
    "id": "17738362",
    "name": "sean rose",
    "login": "sean@box.com",
    "created_at": "2012-03-26T15:43:07-07:00",
    "modified_at": "2012-12-12T11:34:29-08:00",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 2377016,
    "max_upload_size": 262144000,
    "status": "active",
    "job_title": "Employee",
    "phone": "5555555555",
    "address": "555 Office Drive",
    "avatar_url": "https://app.box.com/api/avatar/large/17738362"
}
Suggest Edits

Get User's Info

Retrieves information about a user in the enterprise. Requires enterprise administration authorization.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/users/user_id

Path Params

user_id
string
required

Returns

Returns a single complete user object.

Note:

The GET /users{id} endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for certain admin scopes/users. Disallowed fields will return null.

curl https://api.box.com/2.0/users/10543463
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "type": "user",
    "id": "10543463",
    "name": "Arielle Frey",
    "login": "ariellefrey@box.com",
    "created_at": "2011-01-07T12:37:09-08:00",
    "modified_at": "2014-05-30T10:39:47-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 10737418240,
    "space_used": 558732,
    "max_upload_size": 5368709120,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": "https://blosserdemoaccount.app.box.com/api/avatar/large/10543465"
}
Suggest Edits

Get Enterprise Users

Returns a list of all users for the Enterprise along with their user_id, public_name, and login. This method only works for enterprise admins and service accounts.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/users

Query Params

filter_term
string

A string used to filter the results to only users starting with the filter_term in either the name or the login.

limit
int32

The number of records to return. The default is 100 and the max is 1000.

offset
int32

The record at which to start. The default is 0.

user_type
string

The type of user to search for. Valid values are all, external or managed. If nothing is provided, the default behavior will be managed only

Returns

Returns the list of all users for the Enterprise with their user_id, public_name, and login if the user is an enterprise admin.

Note:

For external users, we will only be matching against login (not name) and will only be doing full matches, no partial matches (so if I call /users?filter_term=joy@box&user_type=external, it will not return joy@box.com).

If the user passes in all, it will return any exact match for external users in addition to partial matches for managed users (but again, only exact login matches for external users).

If a service account is calling this endpoint, it returns either app users or all enterprise users depending on the authorized scope of the app

Note:

For external user, the endpoint will return null for all fields except type, id, name, login, language, timezone, avatar_url, enterprise (if requested via fields).

curl https://api.box.com/2.0/users
-H "Authorization: Bearer ACCESS_TOKEN"
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "total_count": 1,
    "entries": [
        {
            "type": "user",
            "id": "181216415",
            "name": "sean rose",
            "login": "sean+awesome@box.com",
            "created_at": "2012-05-03T21:39:11-07:00",
            "modified_at": "2012-08-23T14:57:48-07:00",
            "language": "en",
            "space_amount": 5368709120,
            "space_used": 52947,
            "max_upload_size": 104857600,
            "status": "active",
            "job_title": "",
            "phone": "5555551374",
            "address": "10 Cloud Way Los Altos CA",
            "avatar_url": "https://app.box.com/api/avatar/large/181216415"
        }
    ]
}
Suggest Edits

Update User

Used to edit the settings and information about a user. To roll a user out of the enterprise (and convert them to a standalone free user), update the special enterprise attribute to be null. The enterprise attribute is only available to enterprise admins.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/users/user_id

Path Params

user_id
string
required

Body Params

notify
boolean

Whether the user should receive an email when they are rolled out of an enterprise

enterprise
string

Setting this to null will roll the user out of the enterprise and make them a free user. When passing a null value, do not pass this value as a string.

name
string

The name of this user

role
string

This user’s enterprise role. Can be coadmin or user

language
string

The language of this user

is_sync_enabled
boolean

Whether or not this user can use Box Sync

job_title
string

The user’s job title

phone
string

The user’s phone number

address
string

The user’s address

space_amount
int32

The user’s total available space amount in byte. A value of -1 grants unlimited storage.

tracking_codes
array of mixed types

An array of key/value pairs set by the user’s admin

can_see_managed_users
boolean

Whether this user can see other enterprise users in its contact list

status
string

Can be active, inactive, cannot_delete_edit, or cannot_delete_edit_upload.

timezone
string

The timezone of this user.

is_exempt_from_device_limits
boolean

Whether to exempt this user from Enterprise device limits

is_exempt_from_login_verification
boolean

Whether or not this user must use two-factor authentication

is_password_reset_required
boolean

Whether or not the user is required to reset password

is_external_collab_restricted
boolean

Whether or not the user is restricted from external collaborations

Returns

Returns the a full user object for the updated user. Errors may be thrown when the fields are invalid or this API call is made from a non-admin account.

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "sean"}' \
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "type": "user",
    "id": "181216415",
    "name": "sean",
    "login": "sean+awesome@box.com",
    "created_at": "2012-05-03T21:39:11-07:00",
    "modified_at": "2012-12-06T18:17:16-08:00",
    "role": "admin",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 1237179286,
    "max_upload_size": 2147483648,
    "tracking_codes": [],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "6509241374",
    "address": "",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false
}
Suggest Edits

Delete User

Deletes a user in an enterprise account.

 

Authentication

 Authentication is required for this endpoint.
deletehttps://api.box.com/2.0/users/user_id

Path Params

user_id
string
required

Query Params

notify
boolean

Determines if the destination user should receive email notification of the transfer.

force
boolean

Whether or not the user should be deleted even if this user still own files.

Returns

An empty 204 response is sent to confirm deletion of the user. If the user still has files in their account and the ‘force’ parameter is not sent, an error is returned.

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
Suggest Edits

Invite User

Invites an existing user to join an Enterprise. The existing user can not be part of another Enterprise and must already have a Box account. Once invited, the user will receive an email and prompt to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope for the enterprise, which can be enabled within your developer console.

 

Authentication

 Authentication is required for this endpoint.
posthttps://api.box.com/2.0/invites

Body Params

enterprise
object
required

The enterprise the user will be invited to

 
id
int32
required

Child of enterprise. The enterprise ID

actionable_by
object
required

The user that will receive the invitation

 
login
string
required

Child of actionable_by. The login of the user that will receive the invitation

Returns

A new invite object will be returned if successful. The status of the invite can also be queried by retrieving the invite object. This can be done by making a GET request to /invites/{invite_id}.

curl https://api.box.com/2.0/invites \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{ "enterprise" : { "id" : "42500" } , "actionable_by" : { "login" : "freeuser@box.com" } }' \
-X POST
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    {
    "type": "invite",
    "id": "238632",
    "invited_to": {
        "type": "enterprise",
        "id": "42500",
        "name": "Blosser Account"
    },
    "actionable_by": {
        "type": "user",
        "id": "229667663",
        "name": "Lleyton Hewitt",
        "login": "freeuser@box.com"
    },
    "invited_by": {
        "type": "user",
        "id": "10523870",
        "name": "Ted Blosser",
        "login": "ted@box.com"
    },
    "status": "pending",
    "created_at": "2014-12-23T12:55:53-08:00",
    "modified_at": "2014-12-23T12:55:53-08:00"
}
Suggest Edits

Move User's Folder

Moves all of the owned content from within one user’s folder into a new folder in another user’s account. You can move folders across users as long as the you have administrative permissions and the ‘source’ user owns the folders. To move everything from the root folder, use “0” which always represents the root folder of a Box account.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/users/user_id/folders/folder_id

Path Params

user_id
string
required
folder_id
string
required

Query Params

notify
boolean

Determines if the destination user should receive email notification of the transfer.

Body Params

owned_by
object
required

The user who the folder will be transferred to

 
id
string
required

Child of owned_by. The ID of the user who the folder will be transferred to

folder_id:

Currently only moving of the root folder (0) is supported.

Returns

Returns the information for the newly created destination folder.. An error is thrown if you do not have the necessary permissions to move the folder.

curl https://api.box.com/2.0/users/USER_ID/folders/FOLDER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"owned_by": {"id": "USER_ID"}}' \
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "type": "folder",
    "id": "11446498",
    "sequence_id": "1",
    "etag": "1",
    "name": "Pictures",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T11:15:04-08:00",
    "description": "Some pictures I took",
    "size": 629644,
    "path_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            }
        ]
    },
    "created_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "17738362",
        "name": "sean rose",
        "login": "sean@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": null,
        "vanity_url": null,
        "is_password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "open",
        "permissions": {
            "can_download": true,
            "can_preview": true
        }
    },
    "folder_upload_email": {
        "access": "open",
        "email": "upload.Picture.k13sdz1@u.box.com"
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active",
    "item_collection": {
        "total_count": 1,
        "entries": [
            {
                "type": "file",
                "id": "5000948880",
                "sequence_id": "3",
                "etag": "3",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
                "name": "tigers.jpeg"
            }
        ],
        "offset": 0,
        "limit": 100
    }
}
Suggest Edits

Change User's Login

Used to convert one of the user’s confirmed email aliases into the user’s primary login.

 

Authentication

 Authentication is required for this endpoint.
puthttps://api.box.com/2.0/users/user_id

Path Params

:user_id
string
required

Body Params

login
string
required

The email alias to become the primary email

Returns

If the user_id is valid and the email address is a confirmed email alias, the updated user object will be returned.

curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"login": "dglover2@box.com"}' ]
-X PUT
Status: {{ results.statusCode[0] }}

Your OAuth2 token has expired

Authenticate via OAuth2
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 200
{
    "type":"user",
    "id":"18180156",
    "name":"Dan Glover",
    "login":"dglover2@box.com",
    "created_at":"2012-09-13T10:19:51-07:00",
    "modified_at":"2012-09-21T10:24:51-07:00",
    "role":"user",
    "language":"en",
    "space_amount":5368709120,
    "space_used":0,
    "max_upload_size":1073741824,
    "tracking_codes":[],
    "see_managed_users":false,
    "sync_enabled":false,
    "status":"active",
    "job_title":"",
    "phone":"",
    "address":"",
    "avatar_url":""
}
Suggest Edits

Get Email Aliases

Retrieves all email aliases for this user. The collection of email aliases does not include the primary login for the user; use GET /users/USER_ID to retrieve the login email address.

 

Authentication

 Authentication is required for this endpoint.
gethttps://api.box.com/2.0/users/user_id/email_aliases

Path Params

user_id
string
required