v1

latestOpenAPI 3.0.2Apache-2.02026-07-142963051.0 MB

File requests

Update file request

Updates a file request. This can be used to activate or deactivate a file request.

put/file_requests/{file_request_id}

Path parameters

file_request_idstring required

The unique identifier that represent a file request.

The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/filerequest/123 the file_request_id is 123.

Headers

if-matchstring

Ensures this item hasn't recently changed before making changes.

Pass in the item's last observed etag value into this header and the endpoint will fail with a 412 Precondition Failed if it has changed since.

Request body

titlestring

An optional new title for the file request. This can be used to change the title of the file request.

This will default to the value on the existing file request.

descriptionstring

An optional new description for the file request. This can be used to change the description of the file request.

This will default to the value on the existing file request.

status'active' | 'inactive'

An optional new status of the file request.

When the status is set to inactive, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a HTTP 404 status code.

This will default to the value on the existing file request.

is_email_requiredboolean

Whether a file request submitter is required to provide their email address.

When this setting is set to true, the Box UI will show an email field on the file request form.

This will default to the value on the existing file request.

is_description_requiredboolean

Whether a file request submitter is required to provide a description of the files they are submitting.

When this setting is set to true, the Box UI will show a description field on the file request form.

This will default to the value on the existing file request.

expires_atstring date-time

The date after which a file request will no longer accept new submissions.

After this date, the status will automatically be set to inactive.

This will default to the value on the existing file request.

Example request

{
  "title": "Please upload required documents",
  "description": "Please upload required documents",
  "status": "active",
  "is_email_required": true,
  "is_description_required": true,
  "expires_at": "2020-09-28T10:53:43-08:00"
}

Response

Returns the updated file request object.

idstring required

The unique identifier for this file request.

type'file_request' required

The value will always be file_request.

titlestring

The title of file request. This is shown in the Box UI to users uploading files.

This defaults to title of the file request that was copied to create this file request.

descriptionstring nullable

The optional description of this file request. This is shown in the Box UI to users uploading files.

This defaults to description of the file request that was copied to create this file request.

status'active' | 'inactive'

The status of the file request. This defaults to active.

When the status is set to inactive, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a HTTP 404 status code.

This defaults to status of file request that was copied to create this file request.

is_email_requiredboolean

Whether a file request submitter is required to provide their email address.

When this setting is set to true, the Box UI will show an email field on the file request form.

This defaults to setting of file request that was copied to create this file request.

is_description_requiredboolean

Whether a file request submitter is required to provide a description of the files they are submitting.

When this setting is set to true, the Box UI will show a description field on the file request form.

This defaults to setting of file request that was copied to create this file request.

expires_atstring date-time

The date after which a file request will no longer accept new submissions.

After this date, the status will automatically be set to inactive.

urlstring

The generated URL for this file request. This URL can be shared with users to let them upload files to the associated folder.

etagstring nullable

The HTTP etag of this file. This can be used in combination with the If-Match header when updating a file request. By providing that header, a change will only be performed on the file request if the etag on the file request still matches the etag provided in the If-Match header.

created_atstring date-time required

The date and time when the file request was created.

updated_atstring date-time required

The date and time when the file request was last updated.

Example response

{
  "id": "42037322",
  "type": "file_request",
  "title": "Please upload documents",
  "description": "Following documents are requested for your process",
  "status": "active",
  "is_email_required": true,
  "is_description_required": true,
  "expires_at": "2020-09-28T10:53:43-08:00",
  "folder": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "url": "/f/19e57f40ace247278a8e3d336678c64a",
  "etag": "1",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "created_at": "2020-09-28T10:53:43-08:00",
  "updated_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "updated_at": "2020-09-28T10:53:43-08:00"
}