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

The PUT endpoint allows updating properties of a running process instance by sending a JSON payload with modified fields like name summary owner tags and form values through an authenticated request.

Tasks > Complete task

An API endpoint marks tasks as complete through POST requests requiring task ID with optional approval status and form field values while supporting both process-based and standalone tasks through different URL structures.

Tasks > Create one-off task

The POST endpoint enables creation of standalone tasks with customizable fields like name description assignees deadline and tags through authenticated API requests that return task details upon successful creation.
Get in touch
About Tallyfy