Skip to content
Tallyfy

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.

Diagram

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:

  1. 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

  2. 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.

  3. 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

Triggers > Launch via API

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