Skip to content
Tallyfy

Update task

Endpoint

Use a different URL depending on the task type:

  • 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 actual IDs.

Request

Headers

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

Body (JSON)

Send a JSON object with only the fields you want to change. Updatable fields include:

  • title (string): New task title. Max 600 characters.
  • summary (string): New task description.
  • deadline (string): New deadline in ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ssZ). Deadlines are automatically adjusted to the organization’s working days.
  • 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).
  • webhook (string): Update the task-specific webhook URL.
  • prevent_guest_comment (boolean): Enable/disable guest comments.
  • position (integer): Change the task’s position order.
  • max_assignable (integer): Set the maximum number of assignees.

Updating form fields with taskdata

Include a taskdata object in the request body. Keys are Form Field IDs (Capture IDs), and values depend on the field type:

  • Text/Textarea: { "taskdata": { "field_id_abc": "New text value" } }
  • Date: { "taskdata": { "field_id_def": "2025-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. Files must be uploaded first.
  • Table: Table fields may need specific formatting - check Swagger or contact Tallyfy support.

Multiple field types in one call

{
    "taskdata": {
        "e4238158ad0949d4ad78c55125b28a99": "normal text field",      // Short text
        "ad789434de1c4d5fade2193d237c5716": "Text Area content here", // Long text/textarea
        "7a54e215a9904096851360917080599f": "yes",                    // Radio button
        "8c0161f92eba4d3da7182fed348f3421": "2025-12-20T14:23:18.128Z", // Date field
        "0e4b280880cc4407a06478a2faa8052b": {                        // Dropdown selection
            "id": 2,
            "text": "Office 365",
            "value": null
        },
        "fe316c2ac44a421cafbf128c9462b8e9": [                        // Multi-select checkboxes
            {
                "id": 1,
                "text": "Slack",
                "value": null,
                "required": true,
                "selected": true
            },
            {
                "id": 2,
                "text": "Teams",
                "value": null,
                "required": false,
                "selected": false
            }
        ]
    }
}

Updating assignees with 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: "2025-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

Returns 200 OK with the full task object after the update, wrapped in a data envelope.

{
  "data": {
    "id": "TASK_ID_TO_UPDATE",
    "title": "Go Updated Task Title",
    "status": "active",
    "owners": {
        "users": [{ "id": 1005, ... }],
        "groups": [],
        "guests": []
     },
    "deadline": "2025-07-01T09:00:00Z",
    "started_at": "2025-06-01T09:00:00Z",
    "last_updated": "2025-05-20T16:00:00Z",
    "taskdata": {
        "text_field_id_example": "Updated value from JS",
        "dropdown_field_id_example": { "id": 3, ... },
        "radio_button_field_id": "Option B"
     },
    "webhook": null,
    "prevent_guest_comment": false,
    "position": 1,
    "is_oneoff_task": false
  }
}

Note that summary only appears in the response when you fetch a single task (not in list responses), or when you include ?with=summary.

Completed tasks can’t be updated - you’ll get a validation error. Other error codes: 404 (task not found), 403 (no permission), 422 (validation failure - wrong field type, missing required fields).

Processes > Update process

Update properties of a running Tallyfy process using PUT - change name summary owner assignees visibility and kick-off form field values.

Templates > Update template

Update an existing template’s properties by sending a PUT request with the required title field and any optional fields you want to change - noting that user or group arrays replace the entire existing list rather than appending to it.

Tasks > Create one-off task

Create standalone one-off tasks in Tallyfy via a POST request with required fields like title, task type, owners, and deadline.

Postman > Task operations and automation

Use Tallyfy’s task API endpoints in Postman to list, complete, update, and comment on tasks within running processes, including form field handling, file attachments, and assignment patterns.
Get in touch
About Tallyfy