Skip to content

Complete task

Endpoint

This endpoint marks a 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 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": "2024-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

A comprehensive guide for reopening completed tasks through DELETE requests with authentication headers showcasing implementation examples in JavaScript Python Java and Go.

Tasks > Delete task

An API endpoint that permanently deletes standalone tasks through DELETE requests with mandatory authorization headers and returns a 204 status code upon successful deletion.

Tasks > Update task

Updates existing tasks by modifying properties like title description deadline assignees and form field values through a PUT request to the Tallyfy API endpoint.

Tasks > Get task

A GET endpoint retrieves comprehensive task details including status owners deadlines and form fields through unique organization and task IDs with optional related data parameters.
Get in touch
About Tallyfy