Launch Tallyfy processes from Workato

Launch Tallyfy processes from Workato recipes

Section titled “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

Section titled “How the integration flows”

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Each prerun value’s shape depends on the field type. The per-type list lives on Launch process.

Mapping dynamic data

Section titled “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

Section titled “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 type	Value to send
Short text, long text, email	A plain string: "John Smith"
Date	An ISO 8601 string: "2026-03-15T00:00:00.000Z"
Radio button	The option’s text as a plain string: "Full-time"
Dropdown	An object with both keys: { "id": 2, "text": "Engineering" }
Checklist (multi-select)	A list of those objects, each carrying "selected": true: [{ "id": 1, "text": "Laptop", "selected": true }]
Table	A list with one entry per column, in column order: ["Widget", "3"]
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.

The multi-select shape needs one extra thing: "selected": true on every option you’re picking. Leave it off and Tallyfy still accepts the recipe step without an error, but the field renders as empty text anywhere it’s used as a {{variable}}.

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

Section titled “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

Section titled “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

Section titled “Common integration patterns”

Launch from a CRM opportunity

Section titled “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

Section titled “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

Section titled “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

Section titled “Troubleshooting”

Process won’t launch?

Section titled “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?

Section titled “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?

Section titled “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.

Related articles

Section titled “Related articles”

Middleware > Workato

Tallyfy’s Workato connector, built on Workato’s Ruby SDK with OAuth 2.0, starts processes…

Triggers > Launch via API

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

Postman > Working with templates and processes

Tallyfy’s API lets you launch processes from templates by posting to the runs endpoint with a…

Workato > Workato actions and triggers

The Workato connector for Tallyfy grew from five actions and three triggers to a full set…

Was this helpful?

YesNo