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

Tallyfy’s API lets you partially update a running process by sending a PUT request with only the fields you want to change — such as name and summary and owner and starred status and assignees — while noting that sending user or group arrays will fully replace all existing assignees of that type rather than appending to them.

Templates > Update template

Tallyfy’s API lets you update an existing template by sending a PUT request with a required title field and optional properties like guidance text and owner and webhook URL and folder assignment and public visibility and auto-naming format and user/group lists where array fields fully replace existing lists rather than appending to them.

Tasks > Create one-off task

Tallyfy’s API lets you create standalone one-off tasks outside any process by sending a POST request to the tasks endpoint with a title and task type and assignees and deadline as required fields along with optional settings like form fields and webhooks and confidentiality flags.

Postman > Task operations and automation

Tallyfy’s API lets you list and filter tasks by status or assignee and complete them via a POST to the completed-tasks endpoint while saving form field captures separately and handling file uploads through multipart form-data and managing task assignments and comments programmatically through Postman.
Get in touch
About Tallyfy