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

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

The API endpoint enables updating task properties like title summary deadline assignees and form field values through a PUT request while handling both process-run tasks and standalone one-off tasks with appropriate response validation.

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.

Tasks > Create one-off task

The POST endpoint enables creation of standalone tasks with customizable fields like name description assignees deadline and tags through authenticated API requests that return task details upon successful creation.
Get in touch
About Tallyfy