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.

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.

Input	Notes	Example
Developer Token string / Required apiKey	A short-lived developer token for testing purposes	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).

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

Triggers

Webhook

Receive and validate webhook requests from Box for webhooks you configure. | key: webhook

Data Sources

Select File or Folder

Select file or folder from Box account base path | key: selectContent | type: picklist

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

Actions

Add Shared Link to File

Adds a shared link to a file | key: addSharedLinkToFile

Input	Notes	Example
Connection connection / Required boxConnection
Shared Link string / Required fields	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
File ID string / Required fileId	The unique identifier of the file	1234567890
Shared Link Access string / Required sharedLinkAccess	The level of access for the shared link. Values: open, company, collaborators	open
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword
Shared Link Permissions code sharedLinkPermissions	The permissions for the shared link
Shared Link Vanity Name string sharedLinkVanityName	The custom vanity name for the shared link	my-shared-link

Add Shared Link to Folder

Adds a shared link to a folder | key: addSharedLinkToFolder

Input	Notes	Example
Connection connection / Required boxConnection
Folder ID string / Required folderId	The unique identifier that represents a folder
Shared Link string / Required sharedLink	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
Shared Link Access string / Required sharedLinkAccess	The level of access for the shared link. Values: open, company, collaborators	open
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword
Shared Link Permissions Folder code sharedLinkPermissions	The permissions for the shared link folder
Shared Link Vanity Name string sharedLinkVanityName	The custom vanity name for the shared link	my-shared-link

Copy Object

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

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

Example Payload for Copy Object

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

Create Folder

Create a Folder at the specified path | key: createFolder

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

Example Payload for Create Folder

{
  "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

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

Example Payload for Create Webhook

{
  "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

Input	Notes
Connection connection / Required boxConnection

Delete Object

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

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

Delete Webhook

Delete a webhook by ID | key: deleteWebhook

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

Example Payload for Delete Webhook

{
  "data": {}
}

Download File

Download the file at the specified path | key: downloadFile

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

Example Payload for Download File

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

Find File For Shared Link

Returns the file represented by a shared link | key: findFileForSharedLink

Input	Notes	Example
Connection connection / Required boxConnection
Fields string fields	A comma-separated list of attributes to include in the response.	type,id,name
Shared Link string / Required sharedLink	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword

Example Payload for Find File For Shared Link

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

Find Folder For Shared Link

Returns the folder represented by a shared link | key: findFolderForSharedLink

Input	Notes	Example
Connection connection / Required boxConnection
Fields string fields	A comma-separated list of attributes to include in the response.	type,id,name
Shared Link string / Required sharedLink	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword

Example Payload for Find Folder For Shared Link

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

Get Current User

Get the information and metadata of the user that is currently logged in | key: getCurrentUser

Input	Notes
Connection connection / Required boxConnection

Example Payload for Get Current User

{
  "data": {
    "type": "user",
    "id": "33333",
    "name": "Example User",
    "login": "user@example.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/deprecated"
  }
}

Get File Download URL

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

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

Example Payload for Get File Download URL

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

Get Shared Link For File

Gets the shared link for a file | key: getSharedLinkForFile

Input	Notes	Example
Connection connection / Required boxConnection
File ID string / Required fileId	The unique identifier of the file	1234567890

Example Payload for Get Shared Link For File

{
  "data": {
    "sharedLink": "https://app.box.com/s/abbvr71aw8a4gb7u2541hlv45l806u5h"
  }
}

Get Shared Link For Folder

Gets the shared link for a folder | key: getSharedLinkForFolder

Input	Notes
Connection connection / Required boxConnection
Folder ID string / Required folderId	The unique identifier that represents a folder

Example Payload for Get Shared Link For Folder

{
  "data": {
    "sharedLink": "https://app.box.com/s/abbvr71aw8a4gb7u2541hlv45l806u5h"
  }
}

List Folder

List Folder contents at the specified path | key: listFolder

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

Example Payload for List Folder

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

List Webhooks

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

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

Example Payload for List Webhooks

{
  "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

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

Example Payload for Move Object

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

Path Details

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

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

Example Payload for Path Details

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

Raw Request

Send raw HTTP request to Box | key: rawRequest

Input	Default	Notes	Example
Connection connection / Required connection
Data string data		The HTTP body payload to send to the URL.	{"exampleKey": "Example Data"}
Debug Request boolean debugRequest	false	Enabling this flag will log out the current request.
File Data string Key Value List fileData		File Data to be sent as a multipart form upload.	[{key: "example.txt", value: "My File Contents"}]
Form Data string Key Value List formData		The Form Data to be sent as a multipart form upload.	[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header string Key Value List headers		A list of headers to send with the request.	User-Agent: curl/7.64.1
Max Retry Count string maxRetries	0	The maximum number of retries to attempt.
Method string / Required method		The HTTP method to use.
Query Parameter string Key Value List queryParams		A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.
Response Type string / Required responseType	json	The type of data you expect in the response. You can request json, text, or binary data.
Retry On All Errors boolean retryAllErrors	false	If true, retries on all erroneous responses regardless of type.
Retry Delay (ms) string retryDelayMS	0	The delay in milliseconds between retries.
Timeout string timeout		The maximum time that a client will await a response to its request	2000
URL string / Required url		Input the path only (/2.0/folders), The base URL is already included (https://api.box.com). For example, to connect to https://api.box.com/2.0/folders, only /2.0/folders is entered in this field.	/2.0/folders
Use Exponential Backoff boolean useExponentialBackoff	false	Specifies whether to use a pre-defined exponential backoff strategy for retries.

Remove Shared Link from File

Removes a shared link from a file | key: removeSharedLinkFromFile

Input	Notes	Example
Connection connection / Required boxConnection
File ID string / Required fileId	The unique identifier of the file	1234567890

Remove Shared Link from Folder

Removes a shared link from a folder | key: removeSharedLinkFromFolder

Input	Notes
Connection connection / Required boxConnection
Folder ID string / Required folderId	The unique identifier that represents a folder

Update Shared Link on File

Updates a shared link on a file | key: updateSharedLinkToFile

Input	Notes	Example
Connection connection / Required boxConnection
File ID string / Required fileId	The unique identifier of the file	1234567890
Shared Link string / Required sharedLink	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
Shared Link Access string / Required sharedLinkAccess	The level of access for the shared link. Values: open, company, collaborators	open
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword
Shared Link Permissions code sharedLinkPermissions	The permissions for the shared link
Shared Link Vanity Name string sharedLinkVanityName	The custom vanity name for the shared link	my-shared-link

Update Shared Link on Folder

Updates a shared link on a folder | key: updateSharedLinkOnFolder

Input	Notes	Example
Connection connection / Required boxConnection
Folder ID string / Required folderId	The unique identifier that represents a folder
Shared Link string / Required sharedLink	The URL of the shared link	https://app.box.com/s/1a2b3c4d5e
Shared Link Access string / Required sharedLinkAccess	The level of access for the shared link. Values: open, company, collaborators	open
Shared Link Password password sharedLinkPassword	The password for the shared link, if any	mypassword
Shared Link Permissions Folder code sharedLinkPermissions	The permissions for the shared link folder
Shared Link Vanity Name string sharedLinkVanityName	The custom vanity name for the shared link	my-shared-link

Upload File

Upload a file to the specified path | key: uploadFile

Input	Notes	Example
Connection connection / Required boxConnection
File Contents data / Required fileContents	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.	My File Contents
Path string / Required path	This represents the files's path. Include a leading /	/path/to/file.txt

Example Payload for Upload File

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

Manage files stored in Box

Description​

Connections​

Box Developer Token​

Box OAuth 2.0 Connection​

Triggers​

Webhook​

Data Sources​

Select File or Folder​

Actions​

Add Shared Link to File​

Add Shared Link to Folder​

Copy Object​

Create Folder​

Create Webhook​

Delete Instance Webhooks​

Delete Object​

Delete Webhook​

Download File​

Find File For Shared Link​

Find Folder For Shared Link​

Get Current User​

Get File Download URL​

Get Shared Link For File​

Get Shared Link For Folder​

List Folder​

List Webhooks​

Move Object​

Path Details​

Raw Request​

Remove Shared Link from File​

Remove Shared Link from Folder​

Update Shared Link on File​

Update Shared Link on Folder​

Upload File​