Working with templates and processes

To launch Tallyfy processes from templates via the API in Postman, you’ll create a run by posting to the runs endpoint with the template’s checklist ID and optional kick-off form data.

API naming vs UI naming

Quick refresher on Tallyfy terminology:

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

This naming difference catches everyone. Just remember: Template equals Checklist, Process equals Run.

Template to process launch flow

This diagram shows the API flow from listing templates to launching and managing processes.

What to notice:

Step 3: Templates are selected dynamically based on business rules
Step 5: Kick-off form data (prerun) gets validated before the run is created
Step 8: The response includes the run ID you’ll need for all subsequent operations

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
Accept: application/json

Response includes:

{
  "data": [
    {
      "id": "checklist_abc123",
      "name": "Employee Onboarding",
      "guidance": "Standard process for new hires",
      "prerun": [
        {
          "id": "field_abc123",
          "label": "Employee Name",
          "field_type": "text"
        }
      ]
    }
  ]
}

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

Getting template details

To see a template’s full structure including kick-off form fields and steps:

GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/checklists/{{CHECKLIST_ID}}?with=steps

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

The prerun array in the response contains all kick-off form fields with their IDs, labels, and types.

Launching a process

Basic launch (no kick-off form)

Create a process by posting to the runs endpoint with a checklist_id:

POST {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs

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

Body:
{
  "checklist_id": "{{CHECKLIST_ID}}",
  "name": "Onboarding - Jane Smith"
}

The checklist_id field is required. It must be the template’s timeline ID (a 32-character UUID without hyphens).

Launch with kick-off form data

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

{
  "checklist_id": "{{CHECKLIST_ID}}",
  "name": "Purchase Request - MacBook Pro",
  "prerun": {
    "field_abc123": "John Smith",
    "field_def456": 2499.99,
    "field_ghi789": "Engineering team needs upgraded hardware"
  }
}

Note the field name is prerun (singular), not preruns.

Finding kick-off field IDs

Three ways to find kick-off form field IDs:

Chrome DevTools method (easiest):
- Launch a process manually in Tallyfy
- Open the Network tab
- Look for the POST request to /runs
- Copy field IDs from the prerun object in the payload
API exploration:
```
GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/checklists/{{CHECKLIST_ID}}
```
Look for prerun in the response - it contains an array of field objects with id and label properties.

Form fields endpoint:

GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/checklists/{{CHECKLIST_ID}}/form-fields

Advanced launch patterns

Launch with task assignments

Override task assignees during launch using the tasks object keyed by step timeline ID:

{
  "checklist_id": "{{CHECKLIST_ID}}",
  "name": "Q1 Budget Review",
  "tasks": {
    "step_timeline_id_1": {
      "owners": {
        "users": ["user_id_123", "user_id_456"],
        "guests": ["guest@example.com"],
        "groups": ["group_id_789"]
      }
    }
  },
  "users": ["user_id_123", "user_id_456"]
}

You can also assign users and groups at the process level with the users and groups arrays.

Conditional launch based on data

Use Postman’s pre-request scripts for dynamic launches:

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

if (amount < 1000) {
    checklistId = "checklist_simple";
} else if (amount < 10000) {
    checklistId = "checklist_manager_approval";
} else {
    checklistId = "checklist_executive_approval";
}

pm.variables.set("CHECKLIST_ID", checklistId);

Bulk process launching

Launch multiple processes efficiently:

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

employees.forEach((emp, index) => {
    setTimeout(() => {
        pm.sendRequest({
            url: `${pm.environment.get("TALLYFY_BASE_URL")}/organizations/${pm.environment.get("TALLYFY_ORG_ID")}/runs`,
            method: 'POST',
            header: {
                'Authorization': `Bearer ${pm.environment.get("TALLYFY_ACCESS_TOKEN")}`,
                'X-Tallyfy-Client': 'APIClient',
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: {
                mode: 'raw',
                raw: JSON.stringify({
                    checklist_id: pm.environment.get("ONBOARDING_CHECKLIST_ID"),
                    name: `Onboarding - ${emp.name}`,
                    prerun: {
                        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

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

Query parameters:
- status: active, complete, problem, archived, delayed
- per_page: 10 (default)
- with: checklist,tasks_meta

Get process details

GET {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs/{{RUN_ID}}?with=tasks,checklist

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

Returns the full process including task statuses, assigned members, form field values, and comments.

Update process metadata

PUT {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs/{{RUN_ID}}

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

Body:
{
  "name": "Updated Process Name",
  "owner_id": "new_owner_user_id"
}

Archive a process (soft delete)

DELETE {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs/{{RUN_ID}}

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

To unarchive (reactivate) a process:

PUT {{TALLYFY_BASE_URL}}/organizations/{{TALLYFY_ORG_ID}}/runs/{{RUN_ID}}/activate

Process monitoring in Postman

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.last_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})`);
    });

    pm.environment.set("STUCK_PROCESSES", JSON.stringify(stuckProcesses));
}

Track completion rates by template

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

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

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

Common pitfalls and solutions

”Template not found” errors

Verify the checklist_id is correct (32-character UUID, no hyphens)
Check the template isn’t archived or in draft mode
Confirm you have launch permission for that template

Kick-off form validation failures

Common issues:

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

Debug by getting template details first - the prerun array shows each field’s type and requirements.

Rate limiting

If you’re bulk launching:

Add delays between requests (200-500ms)
Batch in groups of 10-20
Watch for 429 rate limit responses

Next steps

Automate task operations
Set up webhooks for real-time updates

Processes > Launch process

Tallyfy’s Launch Process API endpoint (POST to /organizations/[org_id]/runs) lets you start a…

Triggers > Launch via API

Tallyfy’s REST API lets you launch processes by sending a POST request with a template ID and…

Code Samples > Managing processes (runs)

Use the Tallyfy API to manage processes (runs) through org-scoped endpoints. Launch, list…

Workato > Launch Tallyfy processes from Workato

Workato recipes can automatically launch Tallyfy processes from triggers in Salesforce, Zendesk…

Was this helpful?

Get in touch

About Tallyfy