Join BoxWorks 2024 to discover what's possible with content and AI!

Create task

post

https://api.box.com/2.0

/tasks

Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately.

Related Guides

Tasks Create a task

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Request Body

action stringin bodyoptional

example"review"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

Value is one of review,complete

completion_rule stringin bodyoptional

example"all_assignees"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 the task in order for it to be considered completed.
any_assignee accepts any one assignee to review or approve the the task in order for it to be considered completed.

Value is one of all_assignees,any_assignee

due_at string (date-time)in bodyoptional

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

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

item objectin body

The file to attach the task to.

item.id stringin bodyrequired

example"11446498"

The ID of the file

item.type stringin bodyrequired

example"file"

file

Value is always file

message stringin bodyoptional

example"Please review"default""

An optional message to include with the task.

Response

201application/jsonTask

Returns the newly created task.

400application/jsonClient error

Returned if the request parameters or body is not valid.

bad_request when the body does not contain a valid request. This may be because the action or completion_rule are not one of the allowed values.

403application/jsonClient error

Returns an error when the user does not have the permission to create a task on the file.

404application/jsonClient error

Returns an error when the file could not be found or the user does not have access to the file.

defaultapplication/jsonClient error

An unexpected client error.

post

Create task

You can now try out some of our APIs live, right here in the documentation.

Request Example

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"
     }'

TypeScript Gen

await client.tasks.createTask({
  item: {
    type: 'file' as CreateTaskRequestBodyItemTypeField,
    id: file.id,
  } satisfies CreateTaskRequestBodyItemField,
  message: 'test message',
  dueAt: date,
  action: 'review' as CreateTaskRequestBodyActionField,
  completionRule: 'all_assignees' as CreateTaskRequestBodyCompletionRuleField,
} satisfies CreateTaskRequestBody);

Python Gen

client.tasks.create_task(
    CreateTaskItem(type=CreateTaskItemTypeField.FILE.value, id=file.id),
    action=CreateTaskAction.REVIEW.value,
    message="test message",
    due_at=date,
    completion_rule=CreateTaskCompletionRule.ALL_ASSIGNEES.value,
)

.NET Gen

await client.Tasks.CreateTaskAsync(requestBody: new CreateTaskRequestBody(item: new CreateTaskRequestBodyItemField() { Type = CreateTaskRequestBodyItemTypeField.File, Id = file.Id }) { Message = "test message", DueAt = date, Action = CreateTaskRequestBodyActionField.Review, CompletionRule = CreateTaskRequestBodyCompletionRuleField.AllAssignees });

Swift Gen (Beta)

try await client.tasks.createTask(requestBody: CreateTaskRequestBody(item: CreateTaskRequestBodyItemField(type: CreateTaskRequestBodyItemTypeField.file, id: file.id), message: "test message", dueAt: date, action: CreateTaskRequestBodyActionField.review, completionRule: CreateTaskRequestBodyCompletionRuleField.allAssignees))

Java

BoxFile file = new BoxFile(api, "id");
Date dueAt = new Date();
file.addTask(BoxTask.Action.REVIEW, "Please review this file.", dueAt);

Python

message = 'Please review this'
due_at = "2014-04-03T11:09:43-07:00"
task = client.file(file_id='11111').create_task(message, due_at)
print(f'Task message is {task.message} and it is due at {task.due_at}')

.NET

var taskParams = new BoxTaskCreateRequest()
{
    Item = new BoxRequestEntity()
    {
        Type = BoxType.file,
        Id = "11111"
    },
    Message = "Please review!"
};
BoxTask task = await client.TasksManager.CreateTaskAsync(taskParams);

Node

var options = {
	message: 'Please review for publication!',
	due_at: '2014-04-03T11:09:43-07:00'
};
client.tasks.create('22222', options)
	.then(task => {
		/* task -> {
			type: 'task',
			id: '11111',
			item: 
			{ type: 'file',
				id: '22222',
				sequence_id: '0',
				etag: '0',
				sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
				name: 'box-logo.png' },
			due_at: '2014-04-03T11:09:43-07:00',
			action: 'review',
			message: 'Please review for publication!',
			task_assignment_collection: { total_count: 0, entries: [] },
			is_completed: false,
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: 'user@example.com' },
			created_at: '2013-04-03T11:12:54-07:00' }
		*/
	});

Response Example

{
  "id": "11446498",
  "type": "task",
  "action": "review",
  "completion_rule": "all_assignees",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "due_at": "2012-12-12T10:53:43-08:00",
  "is_completed": true,
  "item": {
    "id": "12345",
    "type": "file",
    "etag": "1",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "name": "Contract.pdf",
    "sequence_id": "3",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
  },
  "message": "Legal review",
  "task_assignment_collection": {
    "entries": [
      {
        "id": "11446498",
        "type": "task_assignment",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "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"
        }
      }
    ],
    "total_count": 100
  }
}