Create one-off task

Endpoint

POST /organizations/{org_id}/tasks

Creates a standalone one-off task that isn’t part of any process run.

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)

Required fields

• title (string, max 600 chars): The task title.
• task_type (string): One of task, approval, expiring, email, or expiring_email.
• owners (object): Assignees - structure: { "users": [<user_ids>], "guests": ["email@example.com"], "groups": [<group_ids>] }.
• deadline (string): Due date/time in ISO 8601 format.

Optional fields

• description (string): Instructions or details for the task.
• started_at (string): Start date/time in ISO 8601 format.
• separate_task_for_each_assignee (boolean): If true, creates one task per assignee.
• max_assignable (integer): Maximum number of assignees allowed.
• prevent_guest_comment (boolean): Block guests from commenting.
• everyone_must_complete (boolean): Whether all assignees must complete the task.
• can_complete_only_assignees (boolean): Only assigned people can complete it.
• tags (array of strings): 32-character tag IDs to apply.
• form_fields (array): Form fields to capture data on completion.
• webhook (string): URL to call when the task is completed.
• top_secret (boolean): Mark the task as confidential.
• run_id (string): Link this task to an existing process run.

Example body:

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

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 = {
  title: "JS One-Off Task: Review Budget",
  task_type: "task",
  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 = {
    'title': 'Python One-Off Task: Plan Meeting',
    'task_type': 'task',
    'description': 'Schedule and plan the project kickoff meeting.',
    'owners': {
        'users': [1001],
        'guests': [],
        'groups': []
     },
    'deadline': '2025-06-30T17:00:00Z'
}

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 = """
                {"title": "Java One-Off: Simple Task",
                 "task_type": "task",
                 "owners": {"users": [12345]},
                 "deadline": "2025-06-30T17:00:00Z"}""";

        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() == 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"
  "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{}{
    "title":     "Go One-Off Task: Send Update",
    "task_type": "task",
    "owners": map[string][]interface{}{
      "users": {1005},
    },
    "deadline": "2025-06-30T10:00:00Z",
  }

  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 := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading create task response body: %v\n", err)
        return
    }

    if 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::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("title")] = value::string(U("C++ Task: Prepare Presentation"));
        payload[U("task_type")] = value::string(U("task"));

        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"));

        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 Title { get; set; }
        [JsonPropertyName("task_type")]
        public string TaskType { get; set; }
        public TaskOwners Owners { get; set; }
        public string Deadline { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Description { 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?.Title)) {
            Console.WriteLine("Error: Task title 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 201 Created status and a JSON object with the new task’s details.

{
  "data": {
    "id": "new_one_off_task_id_789",
    "increment_id": 1250,
    "title": "Python One-Off Task: Plan Meeting",
    "run_id": null,
    "step_id": null,
    "status": "not-started",
    "task_type": "task",
    "owners": {
      "users": [
        { "id": 1001, "full_name": "Bob", "profile_pic": "..." }
      ],
      "guests": [],
      "groups": []
    },
    "deadline": "2025-06-30T17:00:00.000Z",
    "started_at": null,
    "created_at": "2025-05-20T18:00:00.000Z",
    "last_updated": "2025-05-20T18:00:00.000Z"
  }
}

Save the returned id — you’ll need it to get, update, complete, or delete this task later.

---

Related articles

Tasks > Create a one-off task

Tallyfy lets you create standalone one-off tasks with a deadline and assignee by clicking the + Create button without needing a template which is ideal for urgent work and follow-ups that don’t fit standard processes.

Processes > Launch projects

Tallyfy’s API lets you create ad-hoc projects without a predefined template by using the separate_task_for_each_assignee parameter on the one-off task endpoint which spins up an empty process container and generates individual tasks for each assignee that you can then extend with additional tasks by referencing the returned run_id.

Tasks > Complete task

Tallyfy’s API lets you mark both process tasks and standalone tasks as complete by POSTing the task ID to the appropriate endpoint and optionally handling approval decisions or overriding the completing user while requiring all form fields to be filled beforehand.

Tasks > Update task

Tallyfy’s API lets you update any task (process or one-off) via a PUT request where you can change the title, deadline, assignees, form field values, and other properties — with assignee updates replacing the entire list rather than merging and with different field types like dropdowns and checkboxes requiring specific JSON formatting structures.

Was this helpful?

YesNo