Launch process

Launch Process API Endpoint

This endpoint launches a new process instance (run) based on a specified template (checklist/blueprint).

API vs UI Terminology

Note the terminology difference:

• 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)

The request body requires a JSON object containing the details for the new process run.

Required Fields:

• checklist_id (string): The ID of the template (blueprint) to launch from.
• name (string): The name for this specific process instance.

Optional Fields (Refer to #definitions/createRunInput in Swagger):

• summary (string): Description for this process instance.
• owner_id (integer): User ID of the process owner.
• 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 (array): An array of objects to pre-fill kick-off form fields. The structure depends on the field type (see examples below).
• tasks (object): Define overrides for task properties like assignees and deadlines for specific steps within this run. Keys are Step IDs from the template.
• tags (array of strings): Tag IDs to apply to this process instance.
• users (array of integers): User IDs assigned to the process.
• groups (array of strings): Group IDs assigned to the process.
• roles (array of objects): Role assignments (structure defined in Swagger).
• folders (array of strings): Folder IDs where this process should appear.

Populating kick-off fields using prerun

The prerun array takes objects where the key is the Kick-off Field ID (Prerun ID) and the value depends on the field type:

• Text/Textarea: { "field_id_abc": "Your text value" }
• Date: { "field_id_def": "2024-05-21T10:30:00.000Z" } (ISO 8601 format)
• Radio Button: { "field_id_ghi": "Selected Radio Option Value" }
• Dropdown: { "field_id_jkl": { "id": 2, "text": "Selected Option Text", "value": null } } (Provide the option object as defined in the template)
• Checklist (Multi-select): { "field_id_mno": [{ "id": 1, "text": "Option 1 Text", "value": null, "selected": true }, { "id": 3, "text": "Option 3 Text", "value": null, "selected": true }] } (Array of selected option objects)
• File/Image: { "field_id_pqr": [{ "id": "asset_id_123", "filename": "report.pdf", "version": 1, "url": "...", "uploaded_from": "ko_field", "subject": { "id": "template_id", "type": "Checklist" } }] } (Requires pre-uploading the file and using the returned asset object)

Overriding task properties using tasks

The tasks object allows specifying assignees and deadlines per step for this specific run. The key is the Step ID from the template.

Task Assignment Precedence

1. Assignees defined in the tasks object of the launch request override template step assignees.
2. If not specified in the request, assignees defined on the template step are used.
3. If no assignees are defined anywhere, the task assignment depends on the step’s assign_run_starter setting (defaults to true if not set, meaning the launcher gets assigned). Set it to false and provide empty assignee arrays (users, groups, guests) to ensure a task starts unassigned.

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 Fetch",
  summary: "This instance was started programmatically.",
  // Example prerun data (replace with actual Prerun Field IDs from template)
  prerun: [
    { "kickoff_field_id_1": "Customer XYZ" },
    { "kickoff_field_id_2": "2024-06-15T12:00:00Z" }
  ],
  // Example task override (replace with actual Step IDs from template)
  tasks: {
    "step_id_abc": {
      "deadline": "2024-06-20T17:00:00Z",
      "users": [12345] // Assign specific user ID
    }
  }
};

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 => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to launch process:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        // Check for 200 OK or 201 Created
        console.log(`Process launch requested. Status: ${response.status}`);
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully launched process:');
    console.log(JSON.stringify(data, null, 2));
    // Use data.data.id to get the new run 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'
}

launch_payload = {
    'checklist_id': 'TEMPLATE_ID_TO_LAUNCH',
    'name': 'Process Launched via Python',
    'summary': 'Instance started with requests library.',
    // Example prerun data (replace with actual Prerun Field IDs from template)
    'prerun': [
        { 'prerun_id_cust_name': 'ACME Corp' },
        { 'prerun_id_details': 'High priority request.' }
    ],
    // Example task override (replace with actual Step IDs from template)
    'tasks': {
        'step_id_welcome': {
            'users': [1001] # Assign only user 1001
        },
        'step_id_config': {
             'users': [], # Ensure this task is unassigned
             'groups': [],
             'guests': [],
             'assign_run_starter': False # Crucial if assignees are empty
        }
    }
}

response = None
try:
    response = requests.post(api_url, headers=headers, json=launch_payload)
    response.raise_for_status() # Check for HTTP errors (4xx or 5xx)

    launched_process = response.json()
    print('Successfully launched process:')
    print(json.dumps(launched_process, indent=4))
    # new_run_id = launched_process.get('data', {}).get('id')
    # print(f"New Run ID: {new_run_id}")

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 launching process: {http_err}")
    print(f"Response Body: {error_details}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed launching process: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode successful JSON response after launch")
    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;
// Requires a JSON library like Jackson or Gson
// import com.fasterxml.jackson.databind.ObjectMapper;
// import java.util.Map;
// import java.util.List;
// import java.util.HashMap;
// import java.util.ArrayList;

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

        // --- Payload Construction ---
        // Using a library like Jackson/Gson is strongly recommended for complex payloads
        /*
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> launchData = new HashMap<>();
        launchData.put("checklist_id", "TEMPLATE_ID_TO_LAUNCH"); // Required
        launchData.put("name", "Process Launched via Java"); // Required

        List<Map<String, Object>> prerunList = new ArrayList<>();
        Map<String, Object> prerunField1 = new HashMap<>();
        prerunField1.put("prerun_field_id_1", "Some Value"); // Use actual field ID
        prerunList.add(prerunField1);
        launchData.put("prerun", prerunList);

        Map<String, Object> tasksMap = new HashMap<>();
        Map<String, Object> taskOverride = new HashMap<>();
        taskOverride.put("users", List.of(1001)); // Assign user 1001
        tasksMap.put("step_id_abc", taskOverride); // Use actual step ID
        launchData.put("tasks", tasksMap);

        String jsonPayload = "";
        try {
            jsonPayload = objectMapper.writeValueAsString(launchData);
        } catch (Exception e) {
            System.err.println("Error creating JSON payload: " + e.getMessage());
            return;
        }
        */
        // Simple manual JSON string for example:
        String jsonPayload = "{\"checklist_id\": \"TEMPLATE_ID_TO_LAUNCH\", \"name\": \"Process Launched via Java Simple\"}";
        // --- End Payload ---

        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() == 200 || response.statusCode() == 201) { // Check for 200 OK or 201 Created
                System.out.println("Successfully launched process:");
                System.out.println(response.body());
                // TODO: Consider parsing the JSON response (e.g., using Jackson/Gson)
                // String runId = objectMapper.readTree(response.body()).path("data").path("id").asText();
            } else {
                System.err.println("Failed to launch process. 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/runs", orgId)

  launchData := map[string]interface{}{
    "checklist_id": "TEMPLATE_ID_TO_LAUNCH", // Required
    "name":         "Process Launched via Go", // Required
    "summary":      "Instance started with net/http.",
        // Add prerun and tasks maps here if needed
         "prerun": []map[string]interface{}{
             {"prerun_field_id_1": "Go Value"}, // Use actual Field ID
         },
         "tasks": map[string]interface{}{
             "step_id_abc": map[string]interface{}{ // Use actual Step ID
                 "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 POST 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 making POST request: %v\n", err)
    return
  }
  defer resp.Body.Close()

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

  // Check for successful status codes (e.g., 200 OK or 201 Created)
  if resp.StatusCode != http.StatusOK && 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:")
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal response JSON into Go structs to get run ID etc.
}

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> 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();
                // API might return 201 Created
                if (response.status_code() == status_codes::OK || response.status_code() == status_codes::Created) {
                    std::wcout << L"Successfully launched process:\n" << body.serialize() << std::endl;
                    // Extract new run ID: body[U("data")][U("id")].as_string();
                } else {
                    std::wcerr << L"Failed to launch process. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during launch process: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during launch process response handling: " << e.what() << std::endl;
            }
        });
    });
}

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

        // Example prerun data
        value prerunArray = value::array();
        value prerunField1 = value::object();
        prerunField1[U("kickoff_field_id_1")] = value::string(U("C++ Client Inc."));
        prerunArray[0] = prerunField1;
        payload[U("prerun")] = prerunArray;

        // Example task override
        value tasksObj = value::object();
        value taskOverride = value::object();
        value usersArray = value::array();
        usersArray[0] = value::number(12345);
        taskOverride[U("users")] = usersArray;
        tasksObj[U("step_id_abc")] = taskOverride;
        payload[U("tasks")] = tasksObj;

        LaunchTallyfyProcess(payload).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << 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; // For JsonIgnoreCondition
using System.Threading.Tasks;

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

    // --- Define classes for complex payload parts ---
    public class PrerunField
    {
        // Use Dictionary or specific properties based on field type
        // Example for simple text field (adapt for others like file, dropdown etc.)
         public Dictionary<string, object> Fields { get; set; } // e.g., { "prerun_field_id", "value" }

        // Constructor or factory methods might help build these
    }

    public class TaskOverride
    {
        public List<int> Users { get; set; } // Assignee User IDs
        // Add other override properties like Deadline, Groups, Guests if needed
    }

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

        [JsonPropertyName("name")]
        public string Name { get; set; } // Required

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

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<Dictionary<string, object>> Prerun { get; set; } // Use Dictionary or specific class

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public Dictionary<string, TaskOverride> Tasks { get; set; } // Key is Step ID

        // Add other optional fields like OwnerId, Tags, Folders etc.
    }
    // --- End payload classes ---

    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) || string.IsNullOrWhiteSpace(payload?.Name)) {
            Console.WriteLine("Error: ChecklistId and Name are required to launch a process.");
            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");

            // Serialize payload, ignore nulls
            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) // Check for 200 OK or 201 Created
            {
                Console.WriteLine($"Successfully launched process. Status: {response.StatusCode}");
                 try {
                     using var doc = JsonDocument.Parse(responseBody);
                     Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                     // string newRunId = doc.RootElement.GetProperty("data").GetProperty("id").GetString();
                     // Console.WriteLine($"New Run ID: {newRunId}");
                 } catch (JsonException) {
                     Console.WriteLine(responseBody);
                 }
            }
            else
            {
                Console.WriteLine($"Failed to launch process. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception: {e.Message}");
        }
         catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization/Parsing Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

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

Response

A successful request returns a 200 OK status code and a JSON object containing a data

Related articles

Triggers > Launch via API

The Tallyfy API enables automated process launching through REST endpoints by using authentication credentials and template IDs to trigger workflows and integrate with external systems while supporting data population and customization options.

Pro > Launching

Process launching transforms static workflow templates into active projects by assigning tasks and deadlines to specific team members while maintaining independence between running processes and offering multiple launch methods including manual API triggers and automated schedules.

Templates > Create a template

This API endpoint enables creation of new process templates within organizations by sending a POST request with template configuration including title type ownership permissions and various customization options through multiple programming language implementations.

Tutorials > Launch a process

A comprehensive walkthrough for initiating workflow instances from templates by selecting Launch Process naming the instance customizing settings and monitoring progress through the Tracker view.