Skip to content

Launch process

Launch Process API Endpoint

This endpoint launches a new 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 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.

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 a data

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.

Triggers > Launch via API

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.

Templates > Create a template

A comprehensive POST endpoint for creating organization templates with customizable properties including title summary owner permissions and various configuration options for process management.

Launching > Launch manually

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.