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)

Processes are created 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

Now that you can launch and manage processes:

Processes > Launch process

Launch a new Tallyfy process from a template using POST /organizations/[org_id]/runs with checklist_id and optional fields for kick-off form data, task assignments, and deadlines.

Triggers > Launch via API

Tallyfy’s REST API lets you programmatically launch processes by sending a POST request with a template ID and optional pre-filled data so that external events like CRM deal closures or form submissions can automatically kick off tracked workflows with custom names and assignments and deadlines.

Workato > Launch Tallyfy processes from Workato

Connect Workato to Tallyfy’s API using the HTTP connector to automatically launch processes when events happen in external systems like Salesforce or Zendesk, with authentication headers and kick-off form data mapped through the prerun object.
Get in touch
About Tallyfy