Skip to main content
POST
/
tasks
cURL
curl -i -X POST "https://api.box.com/2.0/tasks" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "item": {
         "id": "11446498",
         "type": "file"
       },
       "action": "review"
     }'
{
  "id": "11446498",
  "type": "task",
  "item": {
    "id": "12345",
    "type": "file",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  },
  "due_at": "2012-12-12T10:53:43-08:00",
  "action": "review",
  "message": "Legal review",
  "task_assignment_collection": {
    "total_count": 100,
    "entries": [
      {
        "id": "11446498",
        "type": "task_assignment",
        "item": {
          "id": "12345",
          "type": "file",
          "etag": "1",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "assigned_to": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "message": "Please review",
        "completed_at": "2012-12-12T10:53:43-08:00",
        "assigned_at": "2012-12-12T10:53:43-08:00",
        "reminded_at": "2012-12-12T10:53:43-08:00",
        "resolution_state": "incomplete",
        "assigned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        }
      }
    ]
  },
  "is_completed": true,
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "completion_rule": "all_assignees"
}

Documentation Index

Fetch the complete documentation index at: https://developer.box.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
item
object
required

The file to attach the task to.

​
action
enum<string>
default:review

The action the task assignee will be prompted to do. Must be

  • review defines an approval task that can be approved or, rejected
  • complete defines a general task which can be completed.
Available options:
review,
complete
Example:

"review"

​
message
string
default:""

An optional message to include with the task.

Example:

"Please review"

​
due_at
string<date-time>

Defines when the task is due. Defaults to null if not provided.

Example:

"2012-12-12T10:53:43-08:00"

​
completion_rule
enum<string>
default:all_assignees

Defines which assignees need to complete this task before the task is considered completed.

  • all_assignees (default) requires all assignees to review or approve the task in order for it to be considered completed.
  • any_assignee accepts any one assignee to review or approve the task in order for it to be considered completed.
Available options:
all_assignees,
any_assignee
Example:

"all_assignees"

Response

Returns the newly created task.

A task allows for file-centric workflows within Box. Users can create tasks on files and assign them to other users for them to complete the tasks.

​
id
string

The unique identifier for this task.

Example:

"11446498"

​
type
enum<string>

The value will always be task.

Available options:
task
Example:

"task"

​
item
File (Mini) · object

The file associated with the task.

​
due_at
string<date-time>

When the task is due.

Example:

"2012-12-12T10:53:43-08:00"

​
action
enum<string>

The type of task the task assignee will be prompted to perform.

Available options:
review,
complete
Example:

"review"

​
message
string

A message that will be included with the task.

Example:

"Legal review"

​
task_assignment_collection
Task assignments · object

A collection of task assignment objects associated with the task.

​
is_completed
boolean

Whether the task has been completed.

Example:

true

​
created_by
User (Mini) · object

The user who created the task.

​
created_at
string<date-time>

When the task object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
completion_rule
enum<string>

Defines which assignees need to complete this task before the task is considered completed.

  • all_assignees requires all assignees to review or approve the task in order for it to be considered completed.
  • any_assignee accepts any one assignee to review or approve the task in order for it to be considered completed.
Available options:
all_assignees,
any_assignee
Example:

"all_assignees"