Delete task

Endpoint

DELETE /organizations/{org_id}/tasks/{task_id}/delete

This endpoint permanently deletes a standalone (“one-off”) task. This action cannot be undone.

Irreversible Action

Permanently deleting a task cannot be undone. All associated task data will be lost. Consider archiving unless you are absolutely sure.

Note

This endpoint is specifically for one-off tasks. To delete tasks within a process run, you typically delete the entire process run using DELETE /organizations/{org_id}/runs/{run_id}/delete.

Request

Replace {org_id} with your Organization ID and {task_id} with the ID of the one-off task to delete permanently.

Headers

• Authorization: Bearer {your_access_token}
• Accept: application/json
• X-Tallyfy-Client: APIClient

Body

No request body is needed for this DELETE request.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const taskId = 'ONE_OFF_TASK_ID_TO_DELETE';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tasks/${taskId}/delete`; // Note the /delete path segment

const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');

fetch(apiUrl, {
    method: 'DELETE',
    headers: headers
})
.then(response => {
    // Expect 204 No Content for successful deletion
    if (response.status === 204) {
        console.log(`Successfully permanently deleted one-off task ${taskId}. Status: ${response.status}`);
        return null; // No body expected for 204
    } else {
        // Try to parse error JSON, fallback to text
        return response.json()
            .catch(() => response.text())
            .then(errData => {
                console.error(`Failed to delete task ${taskId}. Status: ${response.status}`, errData);
                throw new Error(`HTTP error! status: ${response.status}`);
            });
    }
})
.catch(error => {
    console.error(`Error deleting one-off task ${taskId}:`, error.message);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
task_id = 'ONE_OFF_TASK_ID_TO_DELETE'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tasks/{task_id}/delete' # Note /delete path

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient'
}

response = None
try:
    response = requests.delete(api_url, headers=headers)

    # Check specifically for 204 No Content
    if response.status_code == 204:
        print(f'Successfully permanently deleted one-off task {task_id}. Status: {response.status_code}')
    else:
        # Try to get error details, then raise for status if unexpected success or other error
        error_details = ""
        try:
            if response is not None:
                error_details = response.json()
        except json.JSONDecodeError:
            if response is not None:
                error_details = response.text
        print(f"Unexpected status code: {response.status_code}")
        print(f"Response Body: {error_details}")
        response.raise_for_status() # Raise an error for non-204 status

except requests.exceptions.HTTPError as http_err:
    # Error already printed above if status was not 204
    print(f"HTTP error occurred deleting task {task_id}: {http_err}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed deleting task {task_id}: {req_err}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;

public class DeleteOneOffTask {
    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String taskId = "ONE_OFF_TASK_ID_TO_DELETE";
        // Ensure the /delete path segment is included
        String apiUrl = String.format("https://go.tallyfy.com/api/organizations/%s/tasks/%s/delete", orgId, taskId);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .DELETE()
                .build();

        try {
            // Send request expecting no body for 204
            HttpResponse<Void> response = client.send(request, HttpResponse.BodyHandlers.discarding());

            if (response.statusCode() == 204) {
                System.out.println("Successfully permanently deleted one-off task " + taskId + ". Status: " + response.statusCode());
            } else {
                // If status is not 204, the server *might* have sent an error body.
                // We discarded it, so make a new request to try and get the error message.
                System.err.println("Failed to delete one-off task. Status: " + response.statusCode());
                System.err.println("Attempting to retrieve error details...");
                try {
                     HttpRequest errorRequest = HttpRequest.newBuilder(request.uri())
                         .DELETE()
                         .headers(request.headers().map().entrySet().stream().flatMap(e -> e.getValue().stream().map(v -> new String[]{e.getKey(), v})).toArray(String[][]::new))
                         .build();
                     HttpResponse<String> errorResponse = client.send(errorRequest, HttpResponse.BodyHandlers.ofString());
                     System.err.println("Error Response Body: " + errorResponse.body());
                 } catch (Exception errorFetchEx) {
                     System.err.println("Could not retrieve error details: " + errorFetchEx.getMessage());
                 }
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
  "os"
    "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
    if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
    if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
    taskId := "ONE_OFF_TASK_ID_TO_DELETE"
    // Ensure the /delete path segment is included
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tasks/%s/delete", orgId, taskId)

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodDelete, apiUrl, nil)
    if err != nil {
        fmt.Printf("Error creating delete task request for task %s: %v\n", taskId, err)
        return
    }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")

  resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error executing delete task request for task %s: %v\n", taskId, err)
        return
    }
  defer resp.Body.Close()

  if resp.StatusCode == http.StatusNoContent {
        fmt.Printf("Successfully permanently deleted one-off task %s. Status: %d No Content\n", taskId, resp.StatusCode)
  } else {
        // Read body for potential error message
        body, readErr := ioutil.ReadAll(resp.Body)
        if readErr != nil {
            fmt.Printf("Failed to delete task %s. Status: %d. Could not read error body: %v\n", taskId, resp.StatusCode, readErr)
        } else {
            fmt.Printf("Failed to delete task %s. Status: %d\nBody: %s\n", taskId, resp.StatusCode, string(body))
        }
  }
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> DeleteTallyfyOneOffTask(const utility::string_t& taskId)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    // Ensure the /delete path segment is included
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/tasks/") + taskId + U("/delete");

    http_client client(apiUrl);
    http_request request(methods::DEL);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));
    // No request body needed

    return client.request(request).then([taskId](http_response response)
    {
        status_code status = response.status_code();
        utility::string_t taskIdW = taskId;

        if (status == status_codes::NoContent) {
             std::wcout << L"Successfully permanently deleted one-off task " << taskIdW << L". Status: " << status << L" No Content." << std::endl;
        } else {
            // Try to extract error body
            response.extract_string().then([status, taskIdW](utility::string_t errorBody) {
                 std::wcerr << L"Failed to delete task " << taskIdW << L". Status: " << status << std::endl;
                 std::wcerr << L"Response Body: " << errorBody << std::endl;
            }).wait(); // Wait for string extraction in error case
            throw std::runtime_error("Failed to delete task");
        }
    });
}

int main() {
    try {
        DeleteTallyfyOneOffTask(U("ONE_OFF_TASK_ID_TO_DELETE")).wait(); // Replace with actual Task ID
    } catch (const std::exception &e) {
        std::cerr << "Error: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class TallyfyOneOffTaskDeleter
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task DeleteTaskAsync(string taskId)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        // Ensure the /delete path segment is included
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/tasks/{taskId}/delete";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Delete, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");
            // No request body needed

            HttpResponseMessage response = await client.SendAsync(request);

            if (response.StatusCode == System.Net.HttpStatusCode.NoContent)
            {
                Console.WriteLine($"Successfully permanently deleted one-off task {taskId}. Status: {response.StatusCode}");
            }
            else
            {
                // Attempt to read error body
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Failed to delete task {taskId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception deleting task {taskId}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await DeleteTaskAsync("ONE_OFF_TASK_ID_TO_DELETE");
    // }
}

Response

A successful permanent deletion request returns a 204 No Content status code, and no response body.

If the task ID doesn’t exist, is not a one-off task, or you lack permission, an appropriate error status code (404, 403, 400) will be returned, potentially with an error message in the response body.

---

Related articles

Tasks > Archive task

A DELETE endpoint archives standalone tasks by hiding them from default views while preserving data for potential future restoration through authenticated API requests with provided code examples in multiple programming languages.

Processes > Delete process

A DELETE endpoint permanently removes a specific process instance and its associated data with authentication headers returning either 200 OK or 204 No Content status codes upon successful deletion.

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.

Files > Delete file

A DELETE endpoint that removes uploaded files from tasks or kick-off forms by making authorized requests to either /organizations/[org_id]/file/[asset_id] or /organizations/[org]/assets/[assetID] endpoints and returns a 200 OK status code upon successful deletion.