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 (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 (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

(Examples use the endpoint for process tasks. Adapt the URL for one-off tasks.)

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://api.tallyfy.com/organizations/${orgId}/runs/${runId}/tasks/${taskId}`
    : `https://api.tallyfy.com/organizations/${orgId}/tasks/${taskId}`;


const updatePayload = {
  // Example: Update deadline and a text form field
  deadline: "2024-07-01T09:00:00Z",
  taskdata: {
    "text_field_id_example": "Updated value from JS"
  },
  // Example: Change assignees
  owners: {
      users: [1005], // Assign only user 1005
      groups: [],
      guests: []
  }
};


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 => {
    if (!response.ok) {
        // Error handling...
        return response.json().then(errData => { throw new Error(/*...*/); }).catch(() => { throw new Error(/*...*/); });
    }
    return response.json();
})
.then(data => {
    console.log(`Successfully updated task ${taskId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error updating task ${taskId}:`, error);
});

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).

Get in touch
About Tallyfy