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

Tallyfy’s API lets you soft-delete (archive) a standalone one-off task by sending a DELETE request to /organizations/[org_id]/tasks/[task_id] which hides it from default views while preserving all data and allowing restoration later through a separate restore endpoint.

Tags > Delete tag

Tallyfy’s DELETE endpoint at /organizations/[org_id]/tags/[tag_id] permanently removes a tag and all its associations with templates and processes and steps and tasks — returning a 204 No Content response even if the tag ID does not exist.

Processes > Delete process

Tallyfy’s API lets admins permanently and irreversibly delete an already-archived process run along with all its associated tasks and data by sending a DELETE request to the /runs/[run_id]/delete endpoint with code samples provided in six languages.

Tasks > Reopen task

Tallyfy’s API lets you reopen a completed task by sending a DELETE request to the completed-tasks endpoint which effectively removes the completion record and resets the task status back to “in-progress” while clearing out completion-related fields like completed_at and completer_id.

Was this helpful?

YesNo