Skip to content

Update task

Endpoint

This endpoint updates an existing task. The exact endpoint depends on whether it’s a task within a process run or a one-off task:

  • Process Task: PUT /organizations/{org_id}/runs/{run_id}/tasks/{task_id}
  • One-off Task: PUT /organizations/{org_id}/tasks/{task_id}

Replace {org_id}, {run_id} (if applicable), and {task_id} with the appropriate IDs.

Request

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body (JSON)

The request body requires a JSON object containing the task properties you wish to modify. You only need to include the fields you want to change.

Refer to the #definitions/updateTaskInput (for process tasks) or #definitions/updateStandaloneTaskInput (for one-off tasks) schemas in Swagger for available fields. Common updatable fields include:

  • title (string): New task title.
  • summary / description (string): New task description.
  • deadline (string): New deadline in ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ssZ).
  • started_at (string): Set or change the start date/time.
  • owners (object): Update assignees. Structure: { "users": [user_id1, ...], "guests": ["guest@email.com", ...], "groups": [group_id1, ...] }. This replaces existing assignees.
  • taskdata (object): Update form field values (see details below).
  • status (string): Change the task status (use with caution, prefer dedicated complete/reopen endpoints where possible).
  • webhook (string): Update the task-specific webhook URL (one-off tasks).
  • prevent_guest_comment (boolean): Enable/disable guest comments.

Updating form fields using taskdata

To update form field values, include a taskdata object in the request body. The keys within taskdata are the Form Field IDs (Capture IDs), and the values depend on the field type:

  • Text/Textarea: { "taskdata": { "field_id_abc": "New text value" } }
  • Date: { "taskdata": { "field_id_def": "2024-12-31T23:59:59Z" } }
  • Radio Button: { "taskdata": { "field_id_ghi": "Selected Value Text" } }
  • Dropdown: { "taskdata": { "field_id_jkl": { "id": 3, "text": "Chosen Option Text", "value": null } } } (Provide the selected option object)
  • Multi-select Checkboxes: { "taskdata": { "field_id_mno": [ { "id": 1, ..., "selected": true }, { "id": 2, ..., "selected": false }, { "id": 3, ..., "selected": true } ] } } (Provide the full array of options with their selected status)
  • File/Image: See Attach files using the API ↗ sample. Requires pre-uploading.
  • Table: Updating table fields via API might require specific formatting; consult Swagger or Tallyfy support if needed.

Updating assignees using owners

{
  "owners": {
    "users": [1001, 1002], // Assign users 1001 and 1002
    "groups": [], // Remove all group assignments
    "guests": ["new.client@example.com"] // Assign this guest
  }
}

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const runId = 'PROCESS_RUN_ID'; // Or null/omit for one-off task
const taskId = 'TASK_ID_TO_UPDATE';


// Choose the correct URL based on task type
const apiUrl = runId
    ? `https://go.tallyfy.com/api/organizations/${orgId}/runs/${runId}/tasks/${taskId}`
    : `https://go.tallyfy.com/api/organizations/${orgId}/tasks/${taskId}`;


const updatePayload = {
  // Example: Update deadline and a text form field
  deadline: "2024-07-01T09:00:00Z", // Use ISO 8601 Format
  taskdata: {
    "text_field_id_example": "Updated value from JS" // Use actual Field ID
  },
  // Example: Change assignees (this REPLACES the entire list)
  owners: {
      users: [1005], // Assign only user 1005
      groups: [],    // Remove all group assignments
      guests: []     // Remove all guest assignments
  }
};


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');


fetch(apiUrl, {
    method: 'PUT',
    headers: headers,
    body: JSON.stringify(updatePayload)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to update task ${taskId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully updated task ${taskId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error updating task ${taskId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing the full details of the task after the update.

{
  "data": {
    "id": "TASK_ID_TO_UPDATE",
    "title": "Go Updated Task Title", // Updated title
    "summary": "Task summary updated via Python.", // Updated summary
    "status": "active",
    "owners": { // Reflects updated assignees
        "users": [{ "id": 1005, ... }],
        "groups": [],
        "guests": []
     },
    "deadline": "2024-07-01T09:00:00Z", // Updated deadline
    "last_updated": "2024-05-20T16:00:00Z", // Reflects update time
    // ... other task properties ...
    "taskdata": { // Reflects updated form field values
        "text_field_id_example": "Updated value from JS",
        "dropdown_field_id_example": { "id": 3, ... },
        "radio_button_field_id": "Option B"
     }
  }
}

If the task ID is not found, you lack permission, or the request body is invalid (e.g., incorrect field ID, wrong data type for a field), you will receive an appropriate error status code (404, 403, 400, 422).

Processes > Update process

A PUT endpoint that allows updating properties of an existing process run including name summary owner tags folders and form field values while returning the complete updated process data upon success.

Tasks > Complete task

The API endpoint allows marking tasks as complete by sending a POST request with task ID and optional fields like approval status and form data while supporting both process-run tasks and standalone one-off tasks through different URL structures.

Tags > Update tag

The PUT endpoint enables updating an existing tag’s properties like title and color within an organization by sending a JSON request with the new values and receiving the updated tag details in response.
Get in touch
About Tallyfy