Box Task Assignments API
The Box Task Assignments API manages the assignment of tasks to specific users, including creating, retrieving, updating, and deleting task assignments for file review and approval workflows.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Task Assignments API
description: Needs a description.
paths:
/task_assignments:
post:
operationId: post_task_assignments
summary: Box Assign task
tags:
- Task Assignments
x-box-tag: task_assignments
x-box-sanitized: true
description: |-
Assigns a task to a user.
A task can be assigned to more than one user by creating multiple
assignments.
requestBody:
content:
application/json:
schema:
type: object
required:
- task
- assign_to
properties:
task:
type: object
description: The task to assign to a user.
required:
- id
- type
properties:
id:
type: string
description: The ID of the task
example: '11446498'
type:
type: string
description: The type of the item to assign.
example: task
enum:
- task
assign_to:
type: object
description: The user to assign the task to.
properties:
id:
type: string
description: |-
The ID of the user to assign to the
task.
To specify a user by their email
address use the `login` parameter.
example: '3242343'
login:
type: string
description: >-
The email address of the user to assign to the task.
To specify a user by their user ID please use the `id`
parameter.
example: [email protected]
responses:
'201':
description: Returns a new task assignment object.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskAssignment'
'403':
description: >-
Returns an error if a change is attempted for a completed task or
the user
does not have access to the item linked to the task for the given
task
assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Returns an error when the task cannot be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: >-
Returns an error if any of the IDs for this request were not valid,
or if
the targeted user does not have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/task_assignments/{task_assignment_id}:
get:
operationId: get_task_assignments_id
summary: Box Get task assignment
tags:
- Task Assignments
x-box-tag: task_assignments
x-box-sanitized: true
description: Retrieves information about a task assignment.
parameters:
- name: task_assignment_id
description: The ID of the task assignment.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'200':
description: >-
Returns a task assignment, specifying who the task has been assigned
to
and by whom.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskAssignment'
'404':
description: >-
Returns an error when the task assignment could not be found or the
user
does not have access to the file the task is assigned to.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_task_assignments_id
summary: Box Update task assignment
tags:
- Task Assignments
x-box-tag: task_assignments
x-box-sanitized: true
description: |-
Updates a task assignment. This endpoint can be
used to update the state of a task assigned to a user.
parameters:
- name: task_assignment_id
description: The ID of the task assignment.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: >-
An optional message by the assignee that can be added to the
task.
example: Looks good to me
resolution_state:
type: string
description: >-
The state of the task assigned to the user.
* For a task with an `action` value of `complete` this can
be
`incomplete` or `completed`.
* For a task with an `action` of `review` this can be
`incomplete`, `approved`, or `rejected`.
example: completed
enum:
- completed
- incomplete
- approved
- rejected
responses:
'200':
description: Returns the updated task assignment object.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskAssignment'
'400':
description: >-
Returns an error if a resolution state is incompatible with the
action
type of the task.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the task assignment could not be found or the
user
does not have access to the file the task is assigned to.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_task_assignments_id
summary: Box Unassign task
tags:
- Task Assignments
x-box-tag: task_assignments
x-box-sanitized: true
description: Deletes a specific task assignment.
parameters:
- name: task_assignment_id
description: The ID of the task assignment.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the task
assignment was successfully deleted.
'404':
description: >-
Returns an error if the task assignment for the given ID does not
exist
or is inaccessible to your account.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: |-
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
TaskAssignment:
title: Task assignment
type: object
x-box-resource-id: task_assignment
x-box-tag: task_assignments
description: >-
A task assignment defines which task is assigned to which user to
complete.
properties:
id:
type: string
description: The unique identifier for this task assignment
example: '11446498'
type:
type: string
description: '`task_assignment`'
example: task_assignment
enum:
- task_assignment
item:
allOf:
- $ref: '#/components/schemas/File--Mini'
- description: The file that the task has been assigned to.
assigned_to:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user that the task has been assigned to.
message:
type: string
example: Please review
description: >-
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:
type: string
format: date-time
description: |-
The date at which this task assignment was
completed. This will be `null` if the task is not completed yet.
example: '2012-12-12T10:53:43-08:00'
assigned_at:
type: string
format: date-time
description: The date at which this task was assigned to the user.
example: '2012-12-12T10:53:43-08:00'
reminded_at:
type: string
format: date-time
description: |-
The date at which the assigned user was reminded of this task
assignment.
example: '2012-12-12T10:53:43-08:00'
resolution_state:
type: string
description: |-
The current state of the assignment. The available states depend on
the `action` value of the task object.
example: incomplete
enum:
- completed
- incomplete
- approved
- rejected
assigned_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who assigned this task.
tags:
- name: Task Assignments