Update a task assignment

Developer reference

Abstract

Learn how to update task assignments using the API, including assigning, reassigning, and unassigning tasks with required headers and request formats.

Use the PUT /tasks/{task_id}/update-assignment endpoint to update task assignments, including assigning, reassigning, and unassigning tasks.

Request

To update a task's assignment, make a PUT request to the /tasks/{task_id}/update-assignment endpoint.

Replace {task_id} with the ID of the task you want to assign, update, or unassign.

To authenticate your request, include the apikey: API_KEY header. See Manage API keys for more information.

Parameters

In the header of each request, include the If-Match parameter with the task's updated_at timestamp. This prevents updates against an out-of-date task version. If the task has changed since you last retrieved it, the API returns a version mismatch error.

The required body parameters depend on whether you are assigning, reassigning, or removing the task's assignment.

To assign or reassign a task, include the following parameters in an update object:

Field	Type	Description
`assigned_by_id`	string `required`	The ID of the user generating the assignment.
`assigned_to_id`	string `required`	The ID of the user or team, depending on the value of `assigned_to_type`.
`assigned_to_type`	string `required`	Set `assigned_to_type` to `USER` to assign the task to an individual user, or `TEAM` to assign the task to a team.
`assignment_comment`	string or null	A comment added here is visible to the assigned user or team members and is recorded in the entity's audit record.

To unassign a task, include the following parameters in an unassign object:

Field	Type	Description
`assigned_by_id`	string `required`	The ID of the user removing the assignment from the task.
`assignment_comment`	string or null	A comment added here is recorded in the entity's audit record.

Field

Type

Description

assigned_by_id

string

required

The ID of the user removing the assignment from the task.

assignment_comment

string or null

A comment added here is recorded in the entity's audit record.

Sample request: assign or reassign a task

When assigning or reassigning a task, you must specify who the task is assigned to and what type of assignee it is.

curl --request "PUT" \ 
 "https://{api_region}/v5/tasks/{task_id}/update-assignment" \ 
 --header "apikey: API_KEY" \ 
 --header "If-Match: TASK_UPDATED_AT" \ 
 --header "Content-Type: application/json" \ 
 --data "{  
  "update": {   
   "assigned_by_id": "22930149-1fab-4145-94b5-af2031b8de65",   
   "assigned_to_id": "73c0fde6-eb34-47d5-8ccc-1b1d0aa325b6",   
   "assigned_to_type": "USER",   
   "assignment_comment": null  
  } 
 }"

Replace {api_region} with the domain from your region's base URL.

The user or team members assigned to the task receive notification of the assignment by email.

Sample request: unassign a task

Use the unassign object to remove the current assignment from a task.

curl --request "PUT" \ 
 "https://{api_region}/v5/tasks/{task_id}/update-assignment" \ 
 --header "apikey: API_KEY" \ 
 --header "If-Match: TASK_UPDATED_AT" \ 
 --header "Content-Type: application/json" \ 
 --data "{  
  "unassign": {
   "assigned_by_id": "22930149-1fab-4145-94b5-af2031b8de65",   
   "assignment_comment": null
  } 
 }"

Replace {api_region} with the domain from your region's base URL.

Response

A successful request returns the updated task object, including the assignment details (if assigned) and the task's new updated_at value.

{
  "assessment_id": "9f60a03f-b3de-4b19-9361-0380d9aa1e9e",
  "assessment_template_id": "af8498c1-32bd-4453-b407-761eb6440e9b",
  "assignment": {
    "assigned_by_id": "22930149-1fab-4145-94b5-af2031b8de65",
    "assigned_to_id": "73c0fde6-eb34-47d5-8ccc-1b1d0aa325b6",
    "assigned_to_type": "USER",
    "assignment_comment": null
  },
  "c_name": "Review documentation",
  "created_at": "2019-08-24T14:15:22Z",
  "custom_metadata": {},
  "data_version": 0,
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "institution_id": "c75f2c73-5ae4-4f1c-99c0-fc726cd41798",
  "locked_at": "2019-08-24T14:15:22Z",
  "microfrontend_id": "f1ea2a19-6836-4b1f-824d-8a04dfae4cc7",
  "name": null,
  "status": "INCOMPLETE",
  "step_name": "Review",
  "updated_at": "2019-08-24T14:15:22Z",
  "workflow_instance_id": "46ff49d0-5f69-46b0-9de7-5703639a02ce"
}

If the task is unassigned successfully, the assignment value in the response is null.

Troubleshooting

If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.
If you receive a 404 Task not found response, check that the task_id is valid.
A 409 Version mismatch response means that the If-Match value doesn't match the task's current updated_at value. Make sure you're using the most recent update timestamp for the task. You can retrieve the current task details using the Get task by ID endpoint.

For a full list of the possible error codes, view the API reference.