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'; // Omit or use different endpoint for one-off
const taskId = 'TASK_ID_TO_COMPLETE';


// Adjust endpoint based on task type
const apiUrl = runId
    ? `https://api.tallyfy.com/organizations/${orgId}/runs/${runId}/completed-tasks`
    : `https://api.tallyfy.com/organizations/${orgId}/completed-tasks`;


const completePayload = {
  task_id: taskId,
  // Example: Completing an approval task
  // 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 => {
    if (!response.ok) {
        // Error handling...
        return response.json().then(errData => { throw new Error(/*...*/); }).catch(() => { throw new Error(/*...*/); });
    }
    return response.json(); // Completion usually returns the updated task state
})
.then(data => {
    console.log(`Successfully completed task ${taskId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error completing task ${taskId}:`, error);
});

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.

Get in touch
About Tallyfy