Complete Tallyfy tasks from Workato

Complete Tallyfy tasks automatically from Workato recipes

You can complete Tallyfy tasks from Workato recipes whenever something happens in another system - like a document getting signed or a CRM record updating. Here’s how to set it up.

Common use cases

• Mark tasks complete when a document is signed in DocuSign
• Complete approval tasks based on Microsoft Forms responses
• Update task form fields when CRM data changes
• Auto-complete tasks when ERP conditions are met

Prerequisites

• Workato account with HTTP connector access
• Tallyfy API access token (from Settings > Integrations > REST API)
• Your Tallyfy organization ID
• Task IDs or a way to retrieve them dynamically

Setting up task completion

Step 1: Identify the task to complete

You’ll need the task ID and the process (run) ID. Here’s how to get them:

Option A: From a Tallyfy webhook

If Tallyfy triggered your recipe via webhook:

task_id = trigger["task"]["id"]
run_id = trigger["task"]["run_id"]

Option B: List tasks for a process

Use an HTTP GET to retrieve tasks within a specific process:

GET https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/tasks

Option C: Store task IDs when launching

When you launch a process, store the returned task IDs in a lookup table. This works well for recurring workflows.

Step 2: Configure the completion request

Task completion in Tallyfy uses a POST request (not PUT) to a completed-tasks endpoint¹.

1. Add an HTTP action to your Workato recipe
2. Configure the request:
   • Method: POST
   • URL: https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/completed-tasks
   • Headers:
     • Authorization: Bearer {your_access_token}
     • Content-Type: application/json
     • X-Tallyfy-Client: APIClient
3. Set the request body:

   {
     "task_id": "{task_id}"
   }

For approval tasks, you must also include is_approved:

{
  "task_id": "{task_id}",
  "is_approved": true
}

Step 3: Save form field data before completing

If the task has form fields that need values, save them before completing the task. Tallyfy stores form field values (called “captures” in the API) through a separate endpoint:

POST https://go.tallyfy.com/api/organizations/{org_id}/tasks/{task_id}/captures

Each field is saved individually with its ID and value:

{
  "id": 12345,
  "value": "Approved by John Smith"
}

You’ll need to call this endpoint once per field, then complete the task afterward. The field id comes from the task’s capture definitions.

Advanced completion scenarios

Conditional task completion

Only complete tasks when certain conditions are met:

1. Add a conditional action before the HTTP request
2. Check your conditions:

   trigger["order"]["status"] == "shipped" AND
   trigger["order"]["payment_status"] == "paid"

3. Place the completion HTTP action inside the conditional block

Bulk task completion

Need to complete several tasks in a process? Here’s the pattern:

1. Get all tasks for the process:

   GET https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/tasks

2. Use a For each loop in Workato
3. Inside the loop, POST to completed-tasks for each matching task
4. Add a 1-second delay between calls to respect rate limits

Updating form fields without completing

Sometimes you want to save form field data without marking the task done - maybe you’re collecting data in stages. Use the captures endpoint:

POST https://go.tallyfy.com/api/organizations/{org_id}/tasks/{task_id}/captures

{
  "id": 67890,
  "value": "updated_value"
}

You can also update other task properties (like deadline or assignees) via PUT:

PUT https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/tasks/{task_id}

Error handling

Common errors and solutions

Error code	Meaning	Solution
401	Unauthorized	Check your Bearer token and X-Tallyfy-Client header
403	Forbidden	Verify the organization ID is correct
404	Task not found	Confirm the task ID, run ID, and org ID are valid
422	Validation failed	Required form fields probably aren’t filled yet

Retry logic

1. Click the error handler icon on your HTTP action
2. Add a Retry action for transient failures (5xx errors)
3. Configure:
   • Max attempts: 3
   • Interval: 5 seconds
   • Backoff multiplier: 2
4. Log permanent failures for review

Recipe example: DocuSign signature triggers task completion

A real-world pattern - completing a Tallyfy task when someone signs a document:

1. Trigger: DocuSign - Document completed
2. Action 1: List tasks in the Tallyfy process to find the right task

   GET https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/tasks

3. Action 2: Save signature details to form fields

   POST https://go.tallyfy.com/api/organizations/{org_id}/tasks/{task_id}/captures

4. Action 3: Complete the task

   {
     "task_id": "{task_id}"
   }

5. Action 4: Send confirmation email

Troubleshooting

Task won’t complete?

Run through this checklist:

1. Is the task in “active” status? Completed tasks can’t be completed again.
2. Are all required form fields filled? The API returns a 422 if they aren’t.
3. Does the user have permission? Tasks with can_complete_only_assignees set need an assigned user.
4. Are there unresolved issues? Tasks with open problem threads can’t be completed.

Form data not saving?

Usually one of these:

1. The field id must be the numeric capture ID - not the field name
2. The value must match the expected data type
3. Make sure the field actually exists on that task
4. Check that values meet any validation rules on the field

Getting 429 rate limit errors?

You’re sending requests too fast. Fix it by:

1. Adding delays between requests
2. Using exponential backoff
3. Reducing parallel operations

Related articles

Middleware > Workato

Tallyfy’s Workato connector lets you automate workflows between Tallyfy and enterprise systems like Salesforce, SAP, and Workday through OAuth 2.0 authentication with built-in actions for launching processes, completing tasks, and polling triggers for new assignments.

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.

Postman > Task operations and automation

Use Tallyfy’s task API endpoints in Postman to list, complete, update, and comment on tasks within running processes, including form field handling, file attachments, and assignment patterns.

Zapier > Automate tasks using Zapier

Automate Tallyfy task completion through Zapier by finding tasks via template and process name, then marking them complete through the API.

Footnotes

1. Tallyfy uses POST to a completed-tasks resource rather than a PUT/PATCH status change, which differs from many REST APIs ↩

Was this helpful?

YesNo