Delete task

Endpoint

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

This permanently deletes a standalone (one-off) task along with its form fields and captured values. It can’t be undone.

Irreversible action

Permanent deletion wipes the task, its form fields, and all captured form values. You can’t recover any of it. Archive the task instead if you might need it later.

Note

This only works on one-off tasks — not tasks created by a process run. To remove process tasks, delete the entire run with DELETE /organizations/{org_id}/runs/{run_id}/delete.

Request

Replace {org_id} with your Organization ID and {task_id} with the task ID you want to permanently delete.

Headers

Header	Value
Authorization	Bearer {your_access_token}
Accept	application/json
X-Tallyfy-Client	APIClient

Body

No request body is needed.

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`;

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 => {
    if (response.status === 204) {
        console.log(`Permanently deleted task ${taskId}.`);
        return null;
    } else {
        return response.json()
            .catch(() => response.text())
            .then(errData => {
                console.error(`Failed (${response.status}):`, errData);
                throw new Error(`HTTP error ${response.status}`);
            });
    }
})
.catch(error => {
    console.error(`Error deleting task ${taskId}:`, error.message);
});

Python

import requests
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'

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

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

    if response.status_code == 204:
        print(f'Permanently deleted task {task_id}.')
    else:
        print(f'Failed ({response.status_code}): {response.text}')
        response.raise_for_status()

except requests.exceptions.RequestException as e:
    print(f'Error deleting task {task_id}: {e}')

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";
        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 {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 204) {
                System.out.println("Permanently deleted task " + taskId);
            } else {
                System.err.println("Failed (" + response.statusCode() + "): " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        }
    }
}

Go

package main

import (
  "fmt"
  "io"
  "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"
  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 request: %v\n", 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 request: %v\n", err)
    return
  }
  defer resp.Body.Close()

  if resp.StatusCode == http.StatusNoContent {
    fmt.Printf("Permanently deleted task %s.\n", taskId)
  } else {
    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Failed (%d): %s\n", 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;

pplx::task<void> DeleteTask(const utility::string_t& taskId)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    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"));

    return client.request(request).then([taskId](http_response response)
    {
        if (response.status_code() == status_codes::NoContent) {
            std::wcout << L"Permanently deleted task " << taskId << std::endl;
        } else {
            response.extract_string().then([&](utility::string_t body) {
                std::wcerr << L"Failed (" << response.status_code() << L"): " << body << std::endl;
            }).wait();
            throw std::runtime_error("Failed to delete task");
        }
    });
}

int main() {
    try {
        DeleteTask(U("ONE_OFF_TASK_ID_TO_DELETE")).wait();
    } 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 TallyfyTaskDeleter
{
    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";
        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");

            HttpResponseMessage response = await client.SendAsync(request);

            if (response.StatusCode == System.Net.HttpStatusCode.NoContent)
            {
                Console.WriteLine($"Permanently deleted task {taskId}.");
            }
            else
            {
                string body = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Failed ({response.StatusCode}): {body}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
        }
    }

    // static async Task Main(string[] args) => await DeleteTaskAsync("ONE_OFF_TASK_ID_TO_DELETE");
}

Response

A successful deletion returns 204 No Content with no response body.

If the task doesn’t exist or you lack permission, you’ll get an error status (404, 403) with details in the response body.

---

Related articles

Tasks > Archive task

Archive a standalone task using a DELETE request, which soft-deletes it so it’s hidden from default views but can be restored later.

Processes > Delete process

The DELETE endpoint permanently removes an archived process and all its associated data including tasks, comments, and form values with no recovery option.

Tags > Delete tag

Permanently deletes a tag and all its associations from your organization. This can’t be undone - the API returns 204 No Content on success.

Files > Delete file

A DELETE endpoint that permanently removes an uploaded file from a task or kick-off form field using /organizations/[org_id]/file/[asset_id] and returns a 200 OK status with an empty response body.

Was this helpful?

YesNo