Launch process
This endpoint launches a new process instance (run) based on a specified template (checklist/blueprint).
POST /organizations/{org_id}/runs
Replace {org_id}
with your Organization ID.
Authorization: Bearer {your_access_token}
Accept: application/json
X-Tallyfy-Client: APIClient
Content-Type: application/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.
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)
The tasks
object allows specifying assignees and deadlines per step for this specific run. The key is the Step ID from the template.
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);});
import requestsimport jsonimport 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 = Nonetry: 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}")
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(); } }}
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.}
#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)
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 JsonIgnoreConditionusing 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); // }}
A successful request returns a 200 OK
status code and a JSON object containing a data
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.
The Tallyfy API enables automated process launches through REST endpoints by utilizing authentication credentials template IDs and JSON payloads to trigger workflows and integrate with external systems.
A comprehensive POST endpoint for creating organization templates with customizable properties including title summary owner permissions and various configuration options for process management.
A comprehensive guide explaining how to initiate workflows using templates in Tallyfy by selecting launching options setting names assigning tasks and tracking progress through the platform’s interface.
About Tallyfy
- 2025 Tallyfy, Inc.
- Privacy Policy
- Terms of Use
- Report Issue
- Trademarks