Skip to main content

Box Component

Manage files stored in Box

Component key: box

Description#

Box is a file sharing platform that allows teams to collaborate and share files with one another. The Box component allows you to create, list, fetch, move, or delete files and folders in a customer's Box account.

A common integration pattern involves listing files in a file store, and performing a series of actions on the array of files that are returned. See our looping over files quickstart for information about how to create a loop over an array of files.

Box Connections#

Box Developer Token#

A Developer Token is a short-lived (60-minute) token that you can use for testing purposes. A developer token allows you to use the Box API to access your personal Box account only.

note

When your integration is ready for production, you'll need an OAuth 2.0 connection to authenticate your customers' Box accounts. You can also do your testing with OAuth.

InputNotesExample
Input
Developer Token
string
/ Required
Notes
A short-lived developer token for testing purposes
Example
ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

Box OAuth 2.0 Connection#

This component authenticates with Box using OAuth 2.0. You will need to create a Box OAuth 2.0 app in order to authorize your integration to access your customers' Box accounts.

You can follow along with Box's OAuth 2.0 setup documentation here. Note:

  • Be sure to select User Authentication (OAuth 2.0) when creating a Custom App
  • Take note of your Client ID and Client Secret - you'll enter those in Prismatic in a moment
  • Under OAuth 2.0 Redirect URI, enter https://oauth2.prismatic.io/callback
  • Under Application Scopes, select Write all files and folders stored in Box
  • Leave CORS Domains blank

When you add a Box step to an integration, a Box OAuth 2.0 connection will be created for you. Enter the Client ID and Client Secret that you noted earlier. You can leave Scopes blank to use the Application Scopes that you set up previously. Or, you can pare down scopes as desired (reference Box's scopes documentation).

InputDefaultNotes
Input
Authorize URL
string
/ Required
Hidden Field
Default
https://account.box.com/api/oauth2/authorize
Notes
The OAuth 2.0 Authorization URL for Box
Input
Client ID
string
/ Required
Default
Notes
 
Input
Client Secret
password
/ Required
Default
Notes
 
Input
Scopes
string
Default
Notes
A space-delimited set of one or more scopes. Leave this blank to use your app's configured default scopes.
Input
Token URL
string
/ Required
Hidden Field
Default
https://api.box.com/oauth2/token
Notes
The OAuth 2.0 Token URL for Box

Triggers#

Box Webhook#

Handle and validate webhook requests from Box | key: webhook


Actions#

Copy Object#

Copy a Folder or File from one path to another | key: copyObject

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
From Path
string
/ Required
Notes
This represents the source files's path. Include a leading /
Example
/path/to/source/file.txt
Input
To Path
string
/ Required
Notes
This represents the destination files's path. Include a leading /
Example
/path/to/destination/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

Create Folder#

Create a Folder at the specified path | key: createFolder

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": {    "id": "exampleId",    "status": "active",    "name": "Example",    "created_at": "2020-01-01T12:00:00Z",    "description": "Example description.",    "folder": "exampleFolder"  }}

Create Webhook#

Create a webhook to send data from Box to an instance URL | key: createWebhook

InputNotesExample
Input
Webhook URL
string
/ Required
Notes
Reference a flow's URL from the trigger payload
Example
https://example.com/webhook
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Primary Signature Key
password
Notes
A signature key used to validate webhook requests
Example
3T2eTfOvJbAIRoBpXsXPmq0gn8CmF5Q7
Input
Secondary Signature Key
password
Notes
A signature key used to validate webhook requests
Example
3T2eTfOvJbAIRoBpXsXPmq0gn8CmF5Q7
Input
Target ID
string
/ Required
Notes
The ID of the item that will trigger the webhook
Example
375893453
Input
Target Type
string
/ Required
Notes
The type of item that will trigger the webhook
Example
file
Input
Trigger Type
string
/ Required
Value List
Notes
Names of events that this webhook will be triggered for.
Example
 

Output Example Payload#

{  "data": {    "id": "1234",    "type": "webhook",    "target": {      "id": "22222",      "type": "folder"    },    "created_by": {      "type": "user",      "id": "33333",      "name": "Example User",      "login": "user@example.com"    },    "created_at": "2016-05-09T17:41:27-07:00",    "address": "https://example.com/webhook",    "triggers": [      "FILE.DOWNLOADED",      "FILE.UPLOADED"    ]  },  "crossFlowState": {    "primarySignatureKey": "3T2eTfOvJbAIRoBpXsXPmq0gn8CmF5Q7"  }}

Delete Instance Webhooks#

Delete all Box webhooks that point to a flow in this instance | key: deleteInstanceWebhooks

InputNotes
Input
Connection
connection
/ Required
Notes
 

Delete Object#

Delete a Folder or File at the specified path | key: deleteObject

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Delete Webhook#

Delete a webhook by ID | key: deleteWebhook

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Webhook ID
string
/ Required
Notes
The ID of the webhook
Example
375893453

Output Example Payload#

{  "data": {}}

Download File#

Download the file at the specified path | key: downloadFile

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": {    "type": "Buffer",    "data": [      101,      120,      97,      109,      112,      108,      101    ]  },  "contentType": "application/octet"}

Get File Download URL#

Get a URL to download the file at the specified path | key: getFileDownloadUrl

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": "example.com/files/file.txt"}

List Folder#

List Folder contents at the specified path | key: listFolder

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Limit
string
Notes
Provide an integer value for the maximum amount of items that will be returned. Provide a value from 1 to 1000.
Example
100
Input
Marker
string
Notes
Specify the pagination token that's returned by a previous request to retrieve the next page of results
Example
lslTXFcbLQKkb0vP9Kgh5hy0Y0OnC7Z9ZPHPwPmMnxSk3eiDRMkct7D8E
Input
Offset
string
Notes
The offset of the item at which to begin the response.
Example
3
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

List Webhooks#

List all webhooks configured in Box, including those for other integrations | key: listWebhooks

InputDefaultNotesExample
Input
Connection
connection
/ Required
Default
 
Notes
 
Example
 
Input
Limit
string
Default
Notes
Provide an integer value for the maximum amount of items that will be returned. Provide a value from 1 to 1000.
Example
100
Input
Marker
string
Default
Notes
Specify the pagination token that's returned by a previous request to retrieve the next page of results
Example
lslTXFcbLQKkb0vP9Kgh5hy0Y0OnC7Z9ZPHPwPmMnxSk3eiDRMkct7D8E
Input
Show only instance webhooks
boolean
Default
true
Notes
Show only webhooks that point to this instance
Example
 

Output Example Payload#

{  "data": {    "next_marker": "ZmlQZS0xLTE%3D",    "entries": [      {        "id": "1234",        "type": "webhook",        "target": {          "id": "22222",          "type": "folder"        }      },      {        "id": "5678",        "type": "webhook",        "target": {          "id": "11111",          "type": "file"        }      }    ],    "limit": 2  }}

Move Object#

Move a Folder or File from one path to another | key: moveObject

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
From Path
string
/ Required
Notes
This represents the source files's path. Include a leading /
Example
/path/to/source/file.txt
Input
To Path
string
/ Required
Notes
This represents the destination files's path. Include a leading /
Example
/path/to/destination/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

Path Details#

Get detailed information about folders/files in the specified path | key: pathDetails

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "file",      "name": "example"    }  ]}

Upload File#

Upload a file to the specified path | key: uploadFile

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
File Contents
data
/ Required
Notes
The contents to write to a file. This can be a string of text, it can be binary data (like an image or PDF) that was generated in a previous step.
Example
My File Contents
Input
Path
string
/ Required
Notes
This represents the files's path. Include a leading /
Example
/path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}