Create one-off task

Endpoint

POST /organizations/{org_id}/tasks

This endpoint creates a new standalone (“one-off”) Tallyfy task that is not part of a process run initiated from a template.

Request

Replace {org_id} with your Organization ID.

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 defining the new task.

Refer to the #definitions/createStandaloneTaskInput schema in Swagger for all available properties. Key fields include:

• name (string, required): The title of the task.
• description (string): A description or instructions for the task.
• owners (object): Assignees for the task (structure: { "users": [...], "guests": [...], "groups": [...] }).
• deadline (string): When work should be complete on the task (due date/time in ISO 8601 format).
• started_at (string): When work should begin on the task (start date/time in ISO 8601 format).
• task_type (string): Usually member or guest.
• separate_task_for_each_assignee (boolean): If true, creates individual tasks for each person in owners.
• max_assignable (integer): Maximum number of assignees.
• prevent_guest_comment (boolean).
• tags (array of strings): Tag IDs to apply.

Minimal Example Body:

{
  "name": "Follow up with ACME Corp"
}

More Comprehensive Example Body:

{
  "name": "Prepare Q3 Report",
  "description": "Gather data and prepare the quarterly report slides.",
  "owners": {
    "users": [1001, 1002],
    "groups": [],
    "guests": []
  },
  "deadline": "2025-07-15T17:00:00Z",
  "tags": ["reporting", "finance"]
}

Code Samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tasks`;

const taskData = {
  name: "JS One-Off Task: Review Budget",
  description: "Review the draft budget spreadsheet.",
  owners: {
    users: [12345]
  },
  deadline: "2025-06-10T12:00:00Z"
};

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(taskData)
})
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to create one-off task:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log('Successfully created one-off task:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error creating one-off task:', 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')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tasks'

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

task_payload = {
    'name': 'Python One-Off Task: Plan Meeting',
    'description': 'Schedule and plan the project kickoff meeting.',
    'owners': {
        'users': [1001],
        'guests': [],
        'groups': []
     },
    'tags': ["planning", "kickoff"]
}

response = None
try:
    response = requests.post(api_url, headers=headers, json=task_payload)
    response.raise_for_status()

    created_task = response.json()
    print('Successfully created one-off task:')
    print(json.dumps(created_task, indent=4))

except requests.exceptions.HTTPError as http_err:
    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"HTTP error occurred creating task: {http_err}")
    print(f"Response Body: {error_details}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed creating task: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode successful JSON response after creating task")
    if response is not None:
        print(f"Response Text: {response.text}")
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;
import java.time.Duration;

public class CreateOneOffTask {
    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 apiUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/tasks";

        String jsonPayload = "{\"name\": \"Java One-Off: Simple Task\"}";

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200 || response.statusCode() == 201) {
                System.out.println("Successfully created one-off task:");
                System.out.println(response.body());
            } else {
                System.err.println("Failed to create task. Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } 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 (
  "bytes"
  "encoding/json"
  "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" }
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tasks", orgId)

  taskData := map[string]interface{}{
    "name": "Go One-Off Task: Send Update",
        "owners": map[string][]interface{}{
            "users": {1005},
        },
        "deadline": "2025-06-30T10:00:00Z",
        "tags": []string{"go_api", "updates"},
  }

  jsonData, err := json.Marshal(taskData)
  if err != nil {
        fmt.Printf("Error marshalling JSON: %v\n", err)
        return
    }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPost, apiUrl, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Printf("Error creating create task request: %v\n", err)
        return
    }

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

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

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading create task response body: %v\n", err)
        return
    }

    if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
    fmt.Printf("Failed to create task. Status: %d\nBody: %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Println("Successfully created one-off task:")
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
}

C++

#include <iostream>
#include <string>
#include <vector>
#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> CreateTallyfyOneOffTask(const value& taskPayload)
{
    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");

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

    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"));
    request.headers().set_content_type(U("application/json"));
    request.set_body(taskPayload);

    return client.request(request).then([](http_response response)
    {
        return response.extract_json().then([response](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK || response.status_code() == status_codes::Created) {
                    std::wcout << L"Successfully created one-off task:\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to create task. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during create task: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during create task response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        value payload = value::object();
        payload[U("name")] = value::string(U("C++ Task: Prepare Presentation"));

        value owners = value::object();
        value users = value::array();
        users[0] = value::number(12345);
        owners[U("users")] = users;
        payload[U("owners")] = owners;

        payload[U("deadline")] = value::string(U("2025-07-20T17:00:00Z"));

        value tags = value::array();
        tags[0] = value::string(U("presentations"));
        payload[U("tags")] = tags;

        CreateTallyfyOneOffTask(payload).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Threading.Tasks;

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

    public class TaskOwners
    {
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<int> Users { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Guests { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Groups { get; set; }
    }

    public class TaskPayload
    {
        public string Name { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Description { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public TaskOwners Owners { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Deadline { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Tags { get; set; }
    }

    public static async Task CreateOneOffTaskAsync(TaskPayload payload)
    {
        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";

        if (string.IsNullOrWhiteSpace(payload?.Name)) {
            Console.WriteLine("Error: Task Name is required.");
            return;
        }

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

            var options = new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
            string jsonPayload = JsonSerializer.Serialize(payload, options);
            request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode) {
                Console.WriteLine("Successfully created one-off task:");
                 try {
                     using var doc = JsonDocument.Parse(responseBody);
                     Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                 } catch (JsonException) {
                     Console.WriteLine(responseBody);
                 }
            }
            else
            {
                Console.WriteLine($"Failed to create one-off task. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception: {e.Message}");
        }
         catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }
}

Response

A successful request returns a 200 OK or 201 Created status code and a JSON object containing the details of the newly created Tallyfy one-off task, including its assigned id.

{
  "data": {
    "id": "new_one_off_task_id_789",
    "increment_id": 1250,
    "title": "Python One-Off Task: Plan Meeting",
    "description": "Schedule and plan the project kickoff meeting.",
    "run_id": null,
    "step_id": null,
    "status": "active",
    "owners": {
      "users": [
        { "id": 1001, "full_name": "Bob", "profile_pic": "..." }
       ],
      "guests": [],
      "groups": []
     },
    "deadline": null,
    "created_at": "2025-05-20T18:00:00.000Z",
    "last_updated": "2025-05-20T18:00:00.000Z"
  }
}

Make note of the returned id to manage this task later (get, update, complete, delete).

---

Related articles

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 a one-off task

One-off tasks in Tallyfy are standalone action items created by clicking the + Create button and choosing Create task allowing you to assign quick to-dos with deadlines without needing full process templates.

Tasks > Update task

This documentation explains how to update existing Tallyfy tasks using PUT API endpoints with separate URLs for process tasks and one-off tasks and covers modifying properties like title deadline assignees and form field values through taskdata objects with specific formatting requirements for different field types including text dropdowns radio buttons and multi-select checkboxes.

Processes > Launch projects

Tallyfy enables launching empty processes without predefined templates by using the API’s separate_task_for_each_assignee parameter which creates an ad-hoc container for one-off tasks that can be tracked together as a single project - perfect for AI assistants and automation tools that need to create dynamic workflows programmatically.

Was this helpful?

YesNo