Skip to content

Launch process

Launch Process API Endpoint

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

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 Tallyfy 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) from your Tallyfy template 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.

Code Samples

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

Response

A successful request returns a 200 OK status code and a JSON object containing the full details of the newly created Tallyfy process instance.

Postman > Working with templates and processes

Launch Tallyfy processes from templates using Postman by sending API requests with template IDs kick-off form data and member assignments while managing process lifecycle through list update and monitoring operations.

Triggers > Launch via API

Tallyfy’s API enables automated process launching through REST endpoints that integrate with external systems to trigger workflows based on events conditions or schedules while supporting data pre-population and custom process parameters for enterprise-grade automation.

Code Samples > Managing processes (Runs)

The API facilitates process management by enabling users to launch retrieve update and control the lifecycle of running instances while providing integration capabilities for tasks templates and organizational tags.

Tutorials > Launch a process

This tutorial explains how to launch a workflow process from an existing template in Tallyfy by navigating to templates finding your desired template clicking launch completing any kick-off forms naming the process instance optionally reviewing and editing settings then launching to create an active trackable workflow.