Working with templates and processes

To launch Tallyfy processes from templates in Postman, use the template ID with kick-off form data in the request body. The API accepts preruns for form fields and member assignments for process participants.

Understanding templates vs processes

Quick refresher on Tallyfy terminology:

• Templates = Blueprints that define your workflow (API calls them “checklists”)
• Processes = Running instances of templates (API calls them “runs”)
• Kick-off forms = Data collection before launching (API calls them “preruns”)

This naming difference catches everyone. Just remember: Template → Process in Tallyfy UI equals Checklist → Run in API.

Listing available templates

First, see what templates you can launch:

GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/checklists

Headers:
Authorization: Bearer {{TALLYFY_ACCESS_TOKEN}}
X-Tallyfy-Client: APIClient

Response includes:

{
  "data": [
    {
      "id": "checklist_abc123",
      "name": "Employee Onboarding",
      "description": "Standard process for new hires",
      "is_public": false,
      "steps_count": 12
    }
  ]
}

Pro tip: Save template IDs as environment variables for easy reuse.

Launching a process

Basic launch (no kick-off form)

POST {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/checklists/{{TEMPLATE_ID}}/launch

Headers:
Authorization: Bearer {{TALLYFY_ACCESS_TOKEN}}
X-Tallyfy-Client: APIClient
Content-Type: application/json

Body:
{
  "name": "Onboarding - Jane Smith",
  "deadline_date": "2024-02-15"
}

Launch with kick-off form data

Most templates have kick-off forms. Here’s how to pre-fill them:

{
  "name": "Purchase Request - MacBook Pro",
  "preruns": {
    "field_abc123": "John Smith",
    "field_def456": 2499.99,
    "field_ghi789": "Engineering team needs upgraded hardware",
    "field_jkl012": ["Option A", "Option B"]  // Multi-select field
  },
  "deadline_date": "2024-02-20"
}

Finding field IDs

Three ways to find kick-off form field IDs:

1. Chrome DevTools method (easiest):

   • Launch process manually in Tallyfy
   • Open Network tab
   • Look for the launch request
   • Copy field IDs from payload

2. API exploration:

   GET {{TALLYFY_BASE_URL}}/checklists/{{TEMPLATE_ID}}

   Look for prerun_fields in response

3. Postman console:

   • Enable Postman console (View → Show Postman Console)
   • Make requests and inspect full responses

Advanced launch patterns

Launch with specific assignees

Assign members during launch:

{
  "name": "Q1 Budget Review",
  "members": {
    "member_123": ["step_1", "step_3", "step_5"],
    "member_456": ["step_2", "step_4"],
    "member_789": ["step_6", "step_7", "step_8"]
  }
}

Conditional launch based on data

Use pre-request scripts for dynamic launches:

// Determine template based on request amount
const amount = pm.variables.get("purchase_amount");
let templateId;

if (amount < 1000) {
    templateId = "template_simple";
} else if (amount < 10000) {
    templateId = "template_manager_approval";
} else {
    templateId = "template_executive_approval";
}

pm.variables.set("DYNAMIC_TEMPLATE_ID", templateId);

// Set deadline based on priority
const priority = pm.variables.get("priority");
const deadline = new Date();

if (priority === "urgent") {
    deadline.setDate(deadline.getDate() + 1);
} else {
    deadline.setDate(deadline.getDate() + 7);
}

pm.variables.set("DEADLINE", deadline.toISOString().split('T')[0]);

Bulk process launching

Launch multiple processes efficiently:

const employees = [
    { name: "Alice Johnson", dept: "Engineering", start: "2024-02-01" },
    { name: "Bob Smith", dept: "Sales", start: "2024-02-05" },
    { name: "Carol White", dept: "Marketing", start: "2024-02-10" }
];

employees.forEach((emp, index) => {
    setTimeout(() => {
        pm.sendRequest({
            url: `${pm.environment.get("TALLYFY_BASE_URL")}/organizations/${pm.environment.get("TALLYFY_ORG_ID")}/checklists/${pm.environment.get("ONBOARDING_TEMPLATE_ID")}/launch`,
            method: 'POST',
            header: {
                'Authorization': `Bearer ${pm.environment.get("TALLYFY_ACCESS_TOKEN")}`,
                'X-Tallyfy-Client': 'APIClient',
                'Content-Type': 'application/json'
            },
            body: {
                mode: 'raw',
                raw: JSON.stringify({
                    name: `Onboarding - ${emp.name}`,
                    preruns: {
                        field_name: emp.name,
                        field_dept: emp.dept,
                        field_start: emp.start
                    }
                })
            }
        }, (err, res) => {
            if (!err) {
                console.log(`Launched process for ${emp.name}`);
            }
        });
    }, index * 200); // 200ms delay between launches
});

Managing running processes

List active processes

GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs?status=active

Query parameters:
- status: active, completed, archived
- updated_after: 2024-01-01T00:00:00Z
- limit: 50
- offset: 0

Get process details

GET {{TALLYFY_BASE_URL}}/runs/{{PROCESS_ID}}

Returns complete process info including:

• Current status of all tasks
• Assigned members
• Form field values
• Comments and activity

Update process metadata

PUT {{TALLYFY_BASE_URL}}/runs/{{PROCESS_ID}}

Body:
{
  "name": "Updated Process Name",
  "deadline_date": "2024-03-01"
}

Archive completed processes

PUT {{TALLYFY_BASE_URL}}/runs/{{PROCESS_ID}}/archive

Process monitoring patterns

Find stuck processes

Identify processes that haven’t moved in X days:

// In Tests tab after listing processes
const processes = pm.response.json().data;
const stuckThreshold = 3; // days

const stuckProcesses = processes.filter(p => {
    const lastUpdate = new Date(p.updated_at);
    const daysSinceUpdate = (Date.now() - lastUpdate) / (1000 * 60 * 60 * 24);
    return daysSinceUpdate > stuckThreshold && p.status === 'active';
});

if (stuckProcesses.length > 0) {
    console.log(`Found ${stuckProcesses.length} stuck processes:`);
    stuckProcesses.forEach(p => {
        console.log(`- ${p.name} (ID: ${p.id})`);
    });

    // Save for further action
    pm.environment.set("STUCK_PROCESSES", JSON.stringify(stuckProcesses));
}

Process completion tracking

Track completion rates by template:

// After getting all processes
const processes = pm.response.json().data;
const stats = {};

processes.forEach(p => {
    const templateId = p.checklist_id;
    if (!stats[templateId]) {
        stats[templateId] = { total: 0, completed: 0 };
    }
    stats[templateId].total++;
    if (p.status === 'completed') {
        stats[templateId].completed++;
    }
});

Object.entries(stats).forEach(([templateId, data]) => {
    const rate = (data.completed / data.total * 100).toFixed(1);
    console.log(`Template ${templateId}: ${rate}% completion rate`);
});

Common pitfalls and solutions

”Template not found” errors

• Verify template ID is correct
• Check template isn’t archived
• Ensure you have permission to launch

Kick-off form validation failures

Common issues:

• Required fields missing
• Wrong data type (string vs number)
• Invalid option for select fields

Debug by getting template details first to see field requirements.

Process launch limits

Tallyfy may limit concurrent launches. If bulk launching:

• Add delays between requests (100-500ms)
• Batch in groups of 10-20
• Monitor for 429 rate limit errors

Next steps

Now that you can launch and manage processes:

• Automate task operations
• Set up webhooks for real-time updates

Related articles

Processes > Launch process

The Launch Process API endpoint enables creation of new process instances by sending a POST request with template details task assignments and kick-off field data while supporting various programming languages for integration.

Launching > Launch manually

Manual process launching in Tallyfy allows you to initiate workflow instances from templates with complete control over timing and customization by selecting a template naming the instance and clicking launch to create an active trackable process.

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.

Pro > Launching

Process launching in Tallyfy transforms static workflow templates into active trackable processes with specific assignments and deadlines that operate independently with their own timeline participants and progress tracking.