Skip to content
Tallyfy

Launch Tallyfy processes from Workato

Launch Tallyfy processes from Workato recipes

You can connect Workato to Tallyfy’s API so that events in Salesforce, Zendesk, or any other system automatically start processes. Workato’s HTTP connector sends a POST request to Tallyfy with your template ID and kick-off form data - no custom code needed.

How the integration flows

Diagram

Key points:

  • Authentication (step 4) needs a Bearer token and the X-Tallyfy-Client header - missing either causes a 401 error
  • Workato maps your trigger data into the prerun object, keyed by each kick-off field’s timeline ID, which populates those fields automatically (step 2)
  • Error handling (step 8) catches authentication failures, bad template IDs, or data format issues

Prerequisites

You’ll need:

  • A Workato account with HTTP connector access
  • A Tallyfy account with API access
  • Your Tallyfy API token from Settings > Integrations > REST API
  • Your organization ID (found in Settings > Organization)
  • The template ID for the process you want to launch
  • The timeline ID of each kick-off form field you want to pre-fill (see Step 4)

Step 1 - Create the HTTP connection in Workato

  1. In Workato, go to Connections and click Create connection
  2. Search for and select HTTP
  3. Name your connection (e.g., “Tallyfy API”)
  4. Configure these settings:
    • Authentication type: API key
    • How to apply: Header
    • Authorization header format: Custom
    • Custom authorization header: Bearer YOUR_API_TOKEN
    • Other headers: Click Add header and add:
      • Name: X-Tallyfy-Client
      • Value: APIClient
  5. Click Connect to save

Step 2 - Create a recipe to launch processes

  1. Create a new recipe in Workato
  2. Choose your trigger (e.g., “New row in database”, “New Salesforce opportunity”)
  3. Add an HTTP action
  4. Select your Tallyfy HTTP connection
  5. Configure the HTTP request:
    • Request name: Launch Tallyfy Process
    • Method: POST
    • URL: https://go.tallyfy.com/api/organizations/YOUR_ORG_ID/runs
    • Request headers: Add Content-Type with value application/json

The URL includes your organization ID as a path segment. Don’t pass organization_id in the request body - it belongs in the URL.

Step 3 - Configure the request body

Add this JSON to the Request body field:

{
  "checklist_id": "YOUR_TEMPLATE_ID",
  "name": "Process name from trigger data",
  "owner_id": "USER_ID",
  "prerun": {
    "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6": "value from trigger",
    "3c9d1e7fa4b820516d8e2f7a9c0b4d15": "another value"
  }
}

The checklist_id is the template’s timeline ID (what the API calls a “blueprint” internally). The name field sets the process title. The owner_id is optional - if omitted, the authenticated user becomes the owner.

The keys inside prerun are the timeline IDs of your kick-off form fields, each a 32-character hex string. They are not the field labels or aliases. Step 4 shows how to find them.

Mapping dynamic data

Instead of hardcoding values, use Workato’s Formula mode:

  1. Click the Formula mode toggle
  2. Build your JSON dynamically:
{
  "checklist_id": "abc123",
  "name": "Order " + trigger["order_number"] + " - " + trigger["customer_name"],
  "owner_id": "user456",
  "prerun": {
    # Customer name field
    "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6": trigger["customer_name"],
    # Order value field
    "3c9d1e7fa4b820516d8e2f7a9c0b4d15": trigger["total_amount"],
    # Priority field
    "9f2b7c1e4a6d8035b1c7e9d2f4a6b801": trigger["priority"]
  }
}

Keep a comment next to each ID so the recipe stays readable. Nothing in the payload tells you which field an ID belongs to.

Step 4 - Handle kick-off form fields

If your template has a kick-off form, populate those fields through the prerun object:

  1. Check which kick-off form fields are required in your template
  2. Get each field’s timeline ID by calling GET https://go.tallyfy.com/api/organizations/YOUR_ORG_ID/checklists/YOUR_TEMPLATE_ID and reading the id on each entry of the prerun array in the response. Ignore the alias next to it - alias keys don’t work
  3. Use those IDs as the keys in your prerun object
  4. Match the value format to the field type (see the table below)

The value format depends on what kind of field it is:

Field typeValue to send
Short text, long text, emailA plain string: "John Smith"
DateAn ISO 8601 string: "2026-03-15T00:00:00.000Z"
Radio buttonThe option’s text as a plain string: "Full-time"
DropdownAn object with both keys: { "id": 2, "text": "Engineering" }
Checklist (multi-select)A list of those objects: [{ "id": 1, "text": "Laptop" }]
TableA list with one entry per column
Assignees{ "users": [], "guests": [], "groups": [] }

Dropdown and radio look alike in the app but take different shapes here. A radio takes the bare text, a dropdown needs the id and text pair.

Here’s an example with different field types:

{
  "checklist_id": "template123",
  "name": "New Employee: John Smith",
  "owner_id": "hr_manager_id",
  "prerun": {
    "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6": "John Smith",
    "3c9d1e7fa4b820516d8e2f7a9c0b4d15": "2026-03-15T00:00:00.000Z",
    "9f2b7c1e4a6d8035b1c7e9d2f4a6b801": { "id": 2, "text": "Engineering" },
    "6e4a2c80f19b3d75e0a8c246b93f157d": "75000",
    "2d7f9a1c5e3b806478d0a2c4e6f81b39": "Full-time"
  }
}

Reading top to bottom, that’s a text field, a date, a dropdown, a text field holding a number, and a radio button.

Step 5 - Use the Tallyfy response

Tallyfy returns the created process details. You can capture these in your recipe:

  1. Add a Variable action after your HTTP request
  2. Name it “Process Details”
  3. Map fields from the HTTP response:
    • id - The process ID
    • name - The process name
    • created_at - When it was created

Step 6 - Add error handling

  1. Click the HTTP action’s error handler
  2. Add actions for different error scenarios:
    • 401 Unauthorized: Token expired or missing headers
    • 404 Not Found: Template ID doesn’t exist
    • 422 Unprocessable Entity: Validation errors (missing required fields, bad data types)
  3. Add email notifications for failures so you catch problems early

Common integration patterns

Launch from a CRM opportunity

When a Salesforce opportunity hits “Closed Won,” onboarding starts automatically:

  1. Trigger: Salesforce - Updated opportunity
  2. Condition: Status changed to “Closed Won”
  3. Action: Launch Tallyfy customer onboarding process
  4. Pass opportunity data to kick-off form

Launch from a support ticket

Route urgent tickets into a structured escalation process:

  1. Trigger: Zendesk - New ticket
  2. Condition: Priority = “Urgent”
  3. Action: Launch Tallyfy escalation process

Scheduled launches

Run recurring processes on a schedule:

  1. Trigger: Scheduler - Daily/Weekly/Monthly
  2. Action: Launch Tallyfy process
  3. Use date formulas for dynamic names

Troubleshooting

Process won’t launch?

  • Confirm your API token is active and hasn’t expired
  • Check that the X-Tallyfy-Client: APIClient header is included
  • Verify the template ID is the timeline ID, not the template name
  • Make sure the org ID in your URL is correct

Kick-off form data not appearing?

  • Each key in prerun must be a kick-off field’s timeline ID, not the field’s label or alias. A key that matches no field is discarded silently, so the launch still succeeds with that field empty
  • Value formats need to match the field type (see the table in Step 4). A dropdown sent as bare text is rejected
  • Required fields can’t be empty

Getting 422 validation errors?

The API returns detailed validation errors. Check the response body for a details object that tells you which fields failed and why.

Middleware > Workato

Tallyfy’s Workato connector uses OAuth 2.0 and Workato’s Ruby SDK to start processes, complete…

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