Box Developer Platform

Getting Started

Box’s integrations connect the full Box experience to leading business applications. By integrating with Box, your application will be able to access Box user's and content directly within your application. This quickstart guide will take you through the necessary steps to start accessing your own Box account through our API.

1. Creating a Developer Account

To build a Box integration, you will first need to create a developer account and an application using the Content API:

  1. Sign up to create a developer account. If you already have a Box account click the My Apps tab in the header.
  2. Create and name your application.
  3. Retrieve your Client ID (also known as API Key) by selecting Edit Application. The Client ID is listed as client_id under the OAuth2 Parameters at the top of the page.

2. Authenticating Yourself

To get going quickly, visit your application configuration page, select Edit Application, and generate a Developer Token under OAuth2 Parameters. The Developer Token is valid for 1 hour and provides access to your own Box account.

Later, once you're ready to begin working other Box user accounts, see the walkthrough on OAuth 2.0 to get an access token for making API calls. In addition, we provide SDKs in most development languages that contain easy-to-use methods for authentication.

3. Accessing User’s Content

Once you’ve successfully authenticated with the Developer Token, you’ll want to see the contents of your Box account. You can retrieve the contents of any account by listing the contents of the root folder, which for every user is identified by ‘0’. Using cURL, we can do this with the following call:

curl https://api.box.com/2.0/folders/0 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response to this call in my account looks like this (yours will look similar):

{
    "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": "https://www.box.com/shared/static/vspke7y05sb214wjokpk",
        "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
    }
}

4. Uploading and Downloading Files

Now that we’re able to see what’s in the user’s account, let’s try to add some new files through the API. We need to do this as a multi-part form upload, which looks like this in cURL:

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.jpeg

Alert:

Don’t forget the “@” sign when indicating the filename. This tells cURL to read data from the file.

Upon success, you’ll receive a response that should look like this:

{
    "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",
            "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"
        }
    ]
}

Since we now have a file_id available, let’s try downloading that same file just to see how the process works. This is accomplished through a simple GET request to a /files resource like so:

curl https://api.box.com/2.0/files/FILE_ID/content?version=10849 \
-H "Authorization: Bearer ACCESS_TOKEN"

The response to this request will simply be the complete data of the file itself.

Learn More

That’s just the beginning of what you can do with the Box API. Check out the full documentation to learn more about the full set of features and capabilities.

Getting Started