Skip to content
Tallyfy

Launch process

Launch process API endpoint

This endpoint launches a new process (run) from a template (checklist/blueprint).

Endpoint

POST /organizations/{org_id}/runs

Request

Replace {org_id} with your Organization ID.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body (JSON)

Required field:

  • checklist_id (string): The template ID to launch from.

Optional fields:

  • name (string, max 550 chars): Name for this process instance. If omitted, auto-generates as "{template title} - {date}".
  • summary (string): Description for this process instance.
  • owner_id (string): User ID of the process owner.
  • user_id (string): User ID of the process starter (must belong to the organization).
  • starred (boolean): Whether the process is starred.
  • is_public (boolean): Make the process accessible via a public link.
  • parent_id (string): Link this process as a sub-process of another run.
  • prerun (object): Key-value pairs to pre-fill kick-off form fields, keyed by field timeline ID (see below).
  • tasks (object): Overrides for task properties like assignees and deadlines. Keys are step timeline IDs from the template.
  • tags (array of strings): Tag IDs to apply to this process.
  • users (array of strings): User IDs assigned to the process.
  • groups (array of strings): Group IDs assigned to the process.
  • roles (object): Role-based assignments, keyed by role ID.
  • folders (array of strings): Folder IDs where this process should appear.

Populating kick-off fields with prerun

The prerun object is keyed by kick-off field timeline ID. The value format depends on the field type:

  • Text/Textarea: { "field_id_abc": "Your text value" }
  • Date: { "field_id_def": "YYYY-MM-DDTHH:mm:ss.sssZ" } (ISO 8601)
  • Radio button: { "field_id_ghi": "Selected Option Value" }
  • Dropdown: { "field_id_jkl": { "id": 2, "text": "Option Text", "value": null } }
  • Checklist (multi-select): { "field_id_mno": [{ "id": 1, "text": "Option 1", "value": null, "selected": true }] }
  • File/Image: { "field_id_pqr": [{ "id": "asset_id", "filename": "report.pdf", "version": 1, "url": "...", "uploaded_from": "ko_field", "subject": { "id": "template_id", "type": "Checklist" } }] } (requires pre-uploading the file first)

Overriding task properties with tasks

The tasks object lets you set assignees and deadlines per step. Each key is a step timeline ID from the template.

Assignees go inside an owners sub-object:

{
  "step_timeline_id": {
    "deadline": "2025-01-20T17:00:00Z",
    "owners": {
      "users": [12345],
      "guests": ["guest@example.com"],
      "groups": ["group_id"]
    }
  }
}

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs`;


const launchPayload = {
  checklist_id: "TEMPLATE_ID_TO_LAUNCH",
  name: "Process Launched via JS",
  summary: "Started programmatically.",
  // prerun is an object keyed by kick-off field timeline IDs
  prerun: {
    "kickoff_field_id_1": "Customer XYZ",
    "kickoff_field_id_2": "2025-01-15T12:00:00Z"
  },
  // Task overrides keyed by step timeline IDs
  tasks: {
    "step_id_abc": {
      deadline: "2025-01-20T17:00:00Z",
      owners: {
        users: [12345]
      }
    }
  }
};


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');


fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(launchPayload)
})
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to launch process:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        console.log(`Process launched. Status: ${response.status}`);
        return data;
    });
})
.then(data => {
    console.log('Successfully launched process:');
    console.log(JSON.stringify(data, null, 2));
    // Access the new run ID via data.data.id
})
.catch(error => {
    console.error('Error launching process:', error.message);
});

Response

A successful request returns a 201 Created status code and a JSON object with the full details of the newly created process instance, wrapped in a data object.

Postman > Working with templates and processes

Working with Tallyfy templates and processes through the API in Postman requires understanding that the API uses “checklists” for templates and “runs” for processes, with process creation done via POST to the runs endpoint with a checklist_id in the request body.

Triggers > Launch via API

Tallyfy’s REST API lets you programmatically launch processes by sending a POST request with a template ID and optional pre-filled data so that external events like CRM deal closures or form submissions can automatically kick off tracked workflows with custom names and assignments and deadlines.

Templates > Create a template

Create a new Tallyfy template (blueprint) in an organization by POSTing a JSON body with a title, type, and optional settings like summary, owner, webhook, permissions, and kick-off form fields.
Get in touch
About Tallyfy