---
title: "Create task"
method: POST
path: "/tasks"
tags: ["Tasks"]
---

# Create task

`POST /tasks`

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

## Request body

- object
  - `item` object, required — The file to attach the task to.
    - `id` string — The ID of the file.
    - `type` 'file' — The value will always be `file`.
  - `action` 'review' | 'complete' — 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.
  - `message` string — An optional message to include with the task.
  - `due_at` string, date-time — Defines when the task is due. Defaults to `null` if not provided.
  - `completion_rule` 'all_assignees' | 'any_assignee' — 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.

## Response `201`

Returns the newly created task.

- 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.
  - `type` 'task' — The value will always be `task`.
  - `item` object, nullable — The file associated with the task.
    - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
    - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
    - `type` 'file', required — The value will always be `file`.
    - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
    - `name` string — The name of the file.
    - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
    - `file_version` object — The information about the current version of the file.
      - `id` string, required — The unique identifier that represent a file version.
      - `type` 'file_version', required — The value will always be `file_version`.
      - `sha1` string — The SHA1 hash of this version of the file.
  - `due_at` string, date-time — When the task is due.
  - `action` 'review' | 'complete' — The type of task the task assignee will be prompted to perform.
  - `message` string — A message that will be included with the task.
  - `task_assignment_collection` object — A collection of task assignment objects associated with the task.
    - `total_count` integer — The total number of items in this collection.
    - `entries` TaskAssignment[] — A list of task assignments.
      - `id` string — The unique identifier for this task assignment.
      - `type` 'task_assignment' — The value will always be `task_assignment`.
      - `item` object, nullable — The file that the task has been assigned to.
        - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
        - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
        - `type` 'file', required — The value will always be `file`.
        - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
        - `name` string — The name of the file.
        - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
        - `file_version` object — The information about the current version of the file.
          - `id` string, required — The unique identifier that represent a file version.
          - `type` 'file_version', required — The value will always be `file_version`.
          - `sha1` string — The SHA1 hash of this version of the file.
      - `assigned_to` object — The user that the task has been assigned to.
        - `id` string, required — The unique identifier for this user.
        - `type` 'user', required — The value will always be `user`.
        - `name` string — The display name of this user.
        - `login` string, email — The primary email address of this user.
      - `message` string — A message that will is included with the task assignment. This is visible to the assigned user in the web and mobile UI.
      - `completed_at` string, date-time — The date at which this task assignment was completed. This will be `null` if the task is not completed yet.
      - `assigned_at` string, date-time — The date at which this task was assigned to the user.
      - `reminded_at` string, date-time — The date at which the assigned user was reminded of this task assignment.
      - `resolution_state` 'completed' | 'incomplete' | 'approved' | 'rejected' — The current state of the assignment. The available states depend on the `action` value of the task object.
      - `assigned_by` object — The user who assigned this task.
        - `id` string, required — The unique identifier for this user.
        - `type` 'user', required — The value will always be `user`.
        - `name` string — The display name of this user.
        - `login` string, email — The primary email address of this user.
  - `is_completed` boolean — Whether the task has been completed.
  - `created_by` object — The user who created the task.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `created_at` string, date-time — When the task object was created.
  - `completion_rule` 'all_assignees' | 'any_assignee' — 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.

## Other responses

- `400` — 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.
- `403` — Returns an error when the user does not have the permission to create a task on the file.
- `404` — Returns an error when the file could not be found or the user does not have access to the file.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/versions/ba8f087e1a4d/schema)