Skip to content
Tallyfy

Complete task

Endpoint

This endpoint marks a Tallyfy task as complete. The exact endpoint and payload structure differ slightly depending on whether itโ€™s a task within a process run or a one-off task:

  • Process Task: POST /organizations/{org_id}/runs/{run_id}/completed-tasks
  • One-off Task: POST /organizations/{org_id}/completed-tasks

Replace {org_id}, {run_id} (if applicable) 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 specifying the Tallyfy task to complete.

Common Fields:

  • task_id (string, required): The ID of the task to mark as complete.
  • is_approved (boolean, optional): Relevant for approval tasks, set to true to approve, false to reject.
  • taskdata (object, optional): You can optionally provide final form field values within a taskdata object simultaneously with completing the task (same structure as in Update Task โ†—).

Example Body (Simple Completion):

{
  "task_id": "TASK_ID_TO_COMPLETE"
}

Example Body (Completion with Final Field Update):

{
  "task_id": "TASK_ID_TO_COMPLETE",
  "taskdata": {
    "final_notes_field_id": "All checks passed."
  }
}

Example Body (Approval Task - Approve):

{
  "task_id": "APPROVAL_TASK_ID",
  "is_approved": true
}

Code Samples

(Examples use the endpoint for process tasks. Adapt the URL and potentially the payload structure slightly for one-off tasks if needed, based on Swagger definitions #definitions/CompletedProcessTask vs the one for one-off tasks).

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const runId = 'PROCESS_RUN_ID'; // Set to null or omit for one-off tasks
const taskId = 'TASK_ID_TO_COMPLETE'; // Required


// Construct API URL based on whether it's a process task or one-off task
const apiUrl = runId
    ? `https://go.tallyfy.com/api/organizations/${orgId}/runs/${runId}/completed-tasks`
    : `https://go.tallyfy.com/api/organizations/${orgId}/completed-tasks`;


const completePayload = {
  task_id: taskId, // Required
  // Example: Completing an approval task (approve)
  // is_approved: true,
  // Example: Adding a final note while completing
  // taskdata: {
  //   "notes_field_id": "Task completed via API."
  // }
};


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: 'POST',
    headers: headers,
    body: JSON.stringify(completePayload)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to complete task ${taskId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        // Check for 200 OK or 201 Created
        console.log(`Task completion request successful for ${taskId}. Status: ${response.status}`);
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Completed task details:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error completing task ${taskId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing the details of the task, now marked as complete.

{
  "data": {
    "id": "TASK_ID_TO_COMPLETE",
    "title": "Review Proposal",
    "status": "completed", // Status is now complete
    "completed_at": "2025-05-20T17:00:00.000Z", // Completion timestamp
    "completer_id": 1001, // User who completed the task (via API token)
    // ... other task properties, potentially including updated taskdata ...
    // For process tasks, may include 'tasks_changed_by_rules' if completion triggered rules
    "tasks_changed_by_rules": {}
  }
}

If the task cannot be completed (e.g., already complete, permissions issue, invalid ID), an appropriate error status code will be returned.

Tasks > Reopen task

The endpoint allows reopening completed tasks by using DELETE requests to restore them to an active state with proper authentication headers and supports both process-run tasks and standalone one-off tasks through distinct URL patterns.

Tasks > Update task

This documentation explains how to update existing Tallyfy tasks using PUT API endpoints with separate URLs for process tasks and one-off tasks and covers modifying properties like title deadline assignees and form field values through taskdata objects with specific formatting requirements for different field types including text dropdowns radio buttons and multi-select checkboxes.

Tasks > Delete task

A DELETE endpoint permanently removes standalone tasks while preserving process-related tasks that can only be deleted through their parent process run deletion.

Workato > Complete Tallyfy tasks from Workato

Workato recipes can programmatically complete Tallyfy tasks by using HTTP PUT requests to the task completion endpoint with proper authentication and form field data allowing smooth cross-platform automation when events occur in systems like DocuSign or CRM platforms.
Get in touch
About Tallyfy