Skip to content
Tallyfy

Launch via API

Full-seat members

Start a Tallyfy process automatically from another system

Section titled “Start a Tallyfy process automatically from another system”

You can have another system start a Tallyfy process for you, with nobody clicking a button. When a deal closes in your CRM, a customer onboarding process can kick off on its own. When someone submits a form, the matching workflow starts and tracks itself. Your developer sets this up once using Tallyfy’s API1, and from then on it just runs.

This is for teams that want their tools to talk to each other. If you’d rather start a process by hand, by email, or from a public form, see the other trigger options.

What another system can set when it starts a process

Section titled “What another system can set when it starts a process”
  • Pre-fill your kick-off form fields with data it already has, like the customer’s name, the deal value, or a start date
  • Give the process a clear name so it’s easy to find later
  • Assign the right people, groups, and roles to each step
  • Set deadlines
  • Tag the process and drop it in the right folder

Common ways people use this

Section titled “Common ways people use this”
  • CRM: start onboarding the moment a deal closes
  • Document management: kick off an approval when a file is uploaded
  • Sensors and devices (IoT): launch an inspection when a sensor raises an alert
  • External forms: create a process from a form filled out on another site
  • Databases: start a workflow when a record changes

How the trigger works

Section titled “How the trigger works”

Your other system stays in control of when a process starts. It sends one API call, and Tallyfy takes it from there.

An outside system starts a Tallyfy processYour Other SystemTallyfySends back a process IDSomething happensReceives the callFills kick-offform fieldsProcess is running Calls the API

Diagram description: An event in another system, such as a closed deal or an uploaded file, calls the Tallyfy API. Tallyfy receives the call, fills the kick-off form fields from the data it was given, and starts the process. The response hands back a process ID so the calling system can track it.

What to notice:

  • The cause always starts outside Tallyfy. Nobody clicks Launch Process by hand.
  • Tallyfy fills the kick-off form fields from the data in the request, so the process starts pre-filled rather than empty.
  • The response includes a process ID, which is what the calling system uses to track progress afterward.

For developers

Section titled “For developers”

(Skip this unless you’re setting up the technical side.)

To launch a process, send a POST request to Tallyfy’s REST API. You trigger it from your own code, which runs when something happens in another system: a CRM deal closing, a form submission, a sensor alert, and so on.

What you’ll need

Section titled “What you’ll need”
  • A Tallyfy account with API access
  • An OAuth Bearer token for authentication
  • The checklist_id (template ID) you want to launch
  • Familiarity with REST APIs and JSON

How to launch a process

Section titled “How to launch a process”
  1. Get your access token - set up OAuth in Tallyfy and store your Bearer token securely.
  2. Find the template ID and the field IDs - grab the checklist_id from the URL when you’re viewing your template, then call GET /organizations/{org_id}/checklists/{checklist_id} and note the id of every kick-off form field you want to pre-fill. They’re listed in the response’s prerun array.
  3. Send the POST request - call POST /organizations/{org_id}/runs with a JSON body containing checklist_id and process details.
  4. Handle the response - you’ll get a 201 response with the new process data, including its ID. Add error handling for failures.

Pass extra data through the prerun object to pre-fill kick-off form fields. You can also set the process name, per-step assignments (users, groups, and roles), and deadlines in the same request.

Every key inside prerun is a kick-off field’s timeline ID, a 32-character hex string. That’s the id on each entry of the prerun array you got back in step 2. Don’t use the alias sitting next to it in that same response, and don’t use the field’s label. Keys like customer_name never match anything.

Sample API request

Section titled “Sample API request”
POST /organizations/{org_id}/runs HTTP/1.1
Host: go.tallyfy.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
X-Tallyfy-Client: APIClient


{
  "checklist_id": "f7e6d5c4b3a2918070615243342516f0",
  "name": "Customer Onboarding - Acme Corporation",
  "prerun": {
    "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6": "Acme Corporation",
    "3c9d1e7fa4b820516d8e2f7a9c0b4d15": "15000",
    "9f2b7c1e4a6d8035b1c7e9d2f4a6b801": "2024-01-15T00:00:00.000Z"
  }
}

Those three keys are the timeline IDs of the “Customer name”, “Contract value”, and “Start date” kick-off fields.

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

Section titled “Related articles”

Launching > Triggers

Tallyfy offers seven ways to start a process, from manual clicks and form submissions to API…

Footnotes

Section titled “Footnotes”

  1. A way for other software to talk to Tallyfy directly, sending and receiving data without anyone using the screen. ↩

Get in touch
About Tallyfy