Complete Tallyfy tasks from Workato

Complete Tallyfy tasks automatically from Workato recipes

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

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

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

Section titled “Setting up task completion”

Step 1: Identify the task to complete

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

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

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

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

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

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

Section titled “Advanced completion scenarios”

Conditional task completion

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

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

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

Section titled “Error handling”

Common errors and solutions

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

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

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

Section titled “Troubleshooting”

Task won’t complete?

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

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

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

Section titled “Related articles”

Workato > Launch Tallyfy processes from Workato

Workato recipes can automatically launch Tallyfy processes from triggers in Salesforce, Zendesk…

Middleware > Workato

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

Postman > Task operations and automation

Tallyfy’s API lets you list, complete, and update tasks through Postman. Filter by status or…

Tasks > Complete task

Mark process tasks or standalone tasks as complete by POSTing the task ID to the right endpoint…

Footnotes

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