Launch process

Launch process API endpoint

This endpoint launches a new process (run) from a template (checklist/blueprint).

API vs UI terminology

• In the Tallyfy UI: Template -> Process
• In the API: Blueprint/Checklist -> Run

Endpoint

POST /organizations/{org_id}/runs

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 field:

• checklist_id (string): The template ID to launch from.

Optional fields:

• name (string, max 550 chars): Name for this process instance. If it’s omitted, auto-generates as "{template title} - {date}".
• summary (string): Description for this process instance.
• owner_id (string): User ID of the process owner.
• user_id (string): User ID of the process starter (must belong to the organization).
• starred (boolean): Whether the process is starred.
• is_public (boolean): Make the process accessible via a public link.
• parent_id (string): Link this process as a sub-process of another run.
• prerun (object): Key-value pairs to pre-fill kick-off form fields, keyed by field timeline ID (see below).
• tasks (object): Overrides for task properties like assignees and deadlines. Keys are step timeline IDs from the template.
• tags (array of strings): Tag IDs to apply to this process.
• users (array of strings): User IDs assigned to the process.
• groups (array of strings): Group IDs assigned to the process.
• roles (object): Role-based assignments, keyed by role ID.
• folders (array of strings): Folder IDs where this process should appear.

Populating kick-off fields with prerun

The prerun object is keyed by kick-off field timeline ID. The value format depends on the field type:

• Text/Textarea: { "field_id_abc": "Your text value" }
• Date: { "field_id_def": "YYYY-MM-DDTHH:mm:ss.sssZ" } (ISO 8601)
• Radio button: { "field_id_ghi": "Selected Option Value" }
• Dropdown: { "field_id_jkl": { "id": 2, "text": "Option Text", "value": null } }
• Checklist (multi-select): { "field_id_mno": [{ "id": 1, "text": "Option 1", "value": null, "selected": true }] }
• Table: { "field_id_stu": ["Widget", "3"] } (one entry per column, in the order the columns are defined)
• Assignees: { "field_id_vwx": { "users": [12345], "guests": ["guest@example.com"], "groups": ["group_id"] } }
• File/Image: { "field_id_pqr": [{ "id": "asset_id", "filename": "report.pdf", "version": 1, "url": "...", "uploaded_from": "ko_field", "subject": { "id": "template_id", "type": "Checklist" } }] } (requires pre-uploading the file first)

Multi-select needs selected: true on every chosen option

An option without "selected": true passes validation and gets stored, so the request still returns 201 Created. But anywhere that field is used as a {{variable}}, the value renders as empty text. If a multi-select value shows up blank in a task description or an email, this is almost always why.

Sending a table value

A table value is a flat list with exactly one entry per column, in the order the columns are defined on the field. Send a different number of entries and the API rejects the whole request with Number of columns does not match required columns.

For a table field with two columns, Item and Qty:

{
    "checklist_id": "template123",
    "prerun": {
        "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4": ["Widget", "3"]
    }
}

The first entry lands in the first column, the second in the second, and so on. To check the column order, call GET /organizations/{org_id}/checklists/{checklist_id} and read the columns array on that field inside the response’s prerun array. That’s the same response you use to look up the field’s timeline ID.

Overriding task properties with tasks

The tasks object lets you set assignees and deadlines per step. Each key is a step timeline ID from the template.

Assignees go inside an owners sub-object:

{
  "step_timeline_id": {
    "deadline": "2025-01-20T17:00:00Z",
    "owners": {
      "users": [12345],
      "guests": ["guest@example.com"],
      "groups": ["group_id"]
    }
  }
}

Task assignment precedence

1. Assignees in the tasks object override template step assignees.
2. If they’re not specified, Tallyfy uses assignees from the template step.
3. If assignees don’t exist anywhere, assignment depends on the step’s assign_run_starter setting (defaults to true, meaning the launcher gets assigned).

Code samples

Javascript

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

const launchPayload = {
  checklist_id: "TEMPLATE_ID_TO_LAUNCH",
  name: "Process Launched via JS",
  summary: "Started programmatically.",
  // prerun is an object keyed by kick-off field timeline IDs
  prerun: {
    "kickoff_field_id_1": "Customer XYZ",
    "kickoff_field_id_2": "2025-01-15T12:00:00Z"
  },
  // Task overrides keyed by step timeline IDs
  tasks: {
    "step_id_abc": {
      deadline: "2025-01-20T17:00:00Z",
      owners: {
        users: [12345]
      }
    }
  }
};

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(launchPayload)
})
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to launch process:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        console.log(`Process launched. Status: ${response.status}`);
        return data;
    });
})
.then(data => {
    console.log('Successfully launched process:');
    console.log(JSON.stringify(data, null, 2));
    // Access the new run ID via data.data.id
})
.catch(error => {
    console.error('Error launching process:', 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}/runs'

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

# prerun is an object keyed by kick-off field timeline IDs
launch_payload = {
    'checklist_id': 'TEMPLATE_ID_TO_LAUNCH',
    'name': 'Process Launched via Python',
    'summary': 'Instance started with requests library.',
    'prerun': {
        'prerun_id_cust_name': 'ACME Corp',
        'prerun_id_details': 'High priority request.'
    },
    'tasks': {
        'step_id_welcome': {
            'owners': {
                'users': [1001]
            }
        },
        'step_id_config': {
            'owners': {
                'users': [],
                'groups': [],
                'guests': []
            }
        }
    }
}

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

    launched_process = response.json()
    print('Successfully launched process:')
    print(json.dumps(launched_process, indent=4))

except requests.exceptions.HTTPError as http_err:
    error_details = ""
    if response is not None:
        try:
            error_details = response.json()
        except json.JSONDecodeError:
            error_details = response.text
    print(f"HTTP error launching process: {http_err}")
    print(f"Response Body: {error_details}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed: {req_err}")
except Exception as err:
    print(f"Unexpected error: {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 LaunchProcess {

    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 + "/runs";

        // For complex payloads, use Jackson or Gson
        String jsonPayload = """
            {
                "checklist_id": "TEMPLATE_ID_TO_LAUNCH",
                "name": "Process Launched via Java",
                "prerun": {
                    "prerun_field_id_1": "Some Value"
                },
                "tasks": {
                    "step_id_abc": {
                        "owners": { "users": [1001] }
                    }
                }
            }
            """;

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(15))
                .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 launched process:");
                System.out.println(response.body());
            } else {
                System.err.println("Failed to launch process. Status: " + response.statusCode());
                System.err.println("Response: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        }
    }
}

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/runs", orgId)

  // prerun is an object keyed by kick-off field timeline IDs
  launchData := map[string]interface{}{
    "checklist_id": "TEMPLATE_ID_TO_LAUNCH",
    "name":         "Process Launched via Go",
    "prerun": map[string]interface{}{
      "prerun_field_id_1": "Go Value",
    },
    "tasks": map[string]interface{}{
      "step_id_abc": map[string]interface{}{
        "owners": map[string]interface{}{
          "users": []int{1001},
        },
      },
    },
  }

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

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest("POST", apiUrl, bytes.NewBuffer(jsonData))
  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")
  req.Header.Set("Content-Type", "application/json")

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

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

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

  fmt.Println("Successfully launched process:")
  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 <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> LaunchTallyfyProcess(const value& launchPayload)
{
    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("/runs");

    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(launchPayload);

    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 launched process:\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed. Status: " << response.status_code()
                               << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const std::exception& e) {
                std::wcerr << L"Error: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        value payload = value::object();
        payload[U("checklist_id")] = value::string(U("TEMPLATE_ID_TO_LAUNCH"));
        payload[U("name")] = value::string(U("Process Launched via C++"));

        // prerun is an object keyed by kick-off field timeline IDs
        value prerunObj = value::object();
        prerunObj[U("kickoff_field_id_1")] = value::string(U("C++ Client Inc."));
        payload[U("prerun")] = prerunObj;

        // Task overrides with owners sub-object
        value tasksObj = value::object();
        value taskOverride = value::object();
        value ownersObj = value::object();
        value usersArray = value::array();
        usersArray[0] = value::number(12345);
        ownersObj[U("users")] = usersArray;
        taskOverride[U("owners")] = ownersObj;
        tasksObj[U("step_id_abc")] = taskOverride;
        payload[U("tasks")] = tasksObj;

        LaunchTallyfyProcess(payload).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.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 TallyfyProcessLauncher
{
    private static readonly HttpClient client = new HttpClient();

    public class TaskOwners
    {
        [JsonPropertyName("users")]
        public List<int> Users { get; set; }

        [JsonPropertyName("guests")]
        public List<string> Guests { get; set; }

        [JsonPropertyName("groups")]
        public List<string> Groups { get; set; }
    }

    public class TaskOverride
    {
        [JsonPropertyName("owners")]
        public TaskOwners Owners { get; set; }

        [JsonPropertyName("deadline")]
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Deadline { get; set; }
    }

    public class LaunchPayload
    {
        [JsonPropertyName("checklist_id")]
        public string ChecklistId { get; set; }

        [JsonPropertyName("name")]
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Name { get; set; }

        [JsonPropertyName("summary")]
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Summary { get; set; }

        [JsonPropertyName("prerun")]
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public Dictionary<string, object> Prerun { get; set; }

        [JsonPropertyName("tasks")]
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public Dictionary<string, TaskOverride> Tasks { get; set; }
    }

    public static async Task LaunchProcessAsync(LaunchPayload 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}/runs";

        if (string.IsNullOrWhiteSpace(payload?.ChecklistId)) {
            Console.WriteLine("Error: ChecklistId 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($"Launched process. Status: {response.StatusCode}");
                using var doc = JsonDocument.Parse(responseBody);
                Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
            }
            else
            {
                Console.WriteLine($"Failed. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Unexpected error: {ex.Message}");
        }
    }

    // Example usage:
    // static async Task Main(string[] args)
    // {
    //     var payload = new LaunchPayload {
    //         ChecklistId = "TEMPLATE_ID_HERE",
    //         Name = "C# Launched Process",
    //         Prerun = new Dictionary<string, object> {
    //             {"kickoff_field_id_1", "C# Client"}
    //         },
    //         Tasks = new Dictionary<string, TaskOverride> {
    //             {"step_id_abc", new TaskOverride {
    //                 Owners = new TaskOwners { Users = new List<int>{ 12345 } }
    //             }}
    //         }
    //     };
    //     await LaunchProcessAsync(payload);
    // }
}

Response

A successful request returns a 201 Created status code and a JSON object with the full details of the newly created process instance, wrapped in a data object.

Related articles

Postman > Working with templates and processes

Tallyfy’s API lets you launch processes from templates by posting to the runs endpoint with a…

Triggers > Launch via API

Tallyfy’s REST API lets you launch processes by sending a POST request with a template ID and…

Templates > Create a template

Tallyfy’s API lets you create a new process template by sending a POST request to the checklists…

Workato > Launch Tallyfy processes from Workato

Workato recipes can automatically launch Tallyfy processes from triggers in Salesforce, Zendesk…

Was this helpful?

YesNo