Skip to content
Tallyfy

Update process

Endpoint

PUT /organizations/{org_id}/runs/{run_id}

This endpoint allows you to update certain properties of an existing Tallyfy process instance (run).

Request

Replace {org_id} with your Organization ID and {run_id} with the ID of the process run to update.

Headers

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

Body (JSON)

The request body requires a JSON object containing the process properties you wish to modify. You only need to include the fields you want to change.

Refer to the #definitions/createRunInput schema (often similar for updates) in Swagger. Common updatable fields include:

  • name (string): New name for the process instance.
  • summary (string): New summary/description.
  • owner_id (integer): Change the process owner.
  • tags (array of strings): Replaces the current list of tag IDs associated with the process.
  • folders (array of strings): Replaces the current list of folder IDs.
  • prerun (array): Update kick-off form field values (structure depends on field type, see Launch Process).
  • prevent_guest_comment (boolean): Enable/disable guest comments.

Updating form fields using taskdata

To update form field values, include a taskdata object in the request body. The keys within taskdata are the Form Field IDs (Capture IDs), and the values depend on the field type:

Example Body:

{
  "name": "Onboarding - Globex Corp (Updated)",
  "summary": "Updated summary notes for this run.",
  "tags": ["tag_id_urgent", "tag_id_onboarding"],
  "prevent_guest_comment": true
}

Code Samples

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


const updateData = {
  name: "JS Updated Process Name",
  summary: "Adding more details here.",
  prevent_guest_comment: true,
  // Replace tags (get current tags first if adding/removing incrementally)
  // tags: ["tag_id_1", "tag_id_2"]
  // owner_id: 1005
};


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: 'PUT',
    headers: headers,
    body: JSON.stringify(updateData)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to update process ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully updated process ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error updating process ${runId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing the full details of the process run after the update.

{
  "data": {
    "id": "PROCESS_RUN_ID_TO_UPDATE",
    "name": "Onboarding - Globex Corp (Updated)", // Updated name
    "summary": "Updated summary notes for this run.", // Updated summary
    "tags": ["tag_id_urgent", "tag_id_onboarding"], // Updated tags
    // ... other process properties reflecting the current state ...
    "last_updated": "YYYY-MM-DDTHH:MM:SSZ", // Timestamp reflects the update
    "notes": "Updated process notes."
  }
}

If the run ID is not found, you lack permission, or the request body is invalid, an appropriate error status code (404, 403, 400, 422) will be returned.

Tasks > Update task

This documentation explains how to update existing Tallyfy tasks using PUT API endpoints with separate URLs for process tasks and one-off tasks and covers modifying properties like title deadline assignees and form field values through taskdata objects with specific formatting requirements for different field types including text dropdowns radio buttons and multi-select checkboxes.

Templates > Update template

This endpoint enables updating existing process template properties by sending a PUT request with only the fields you want to modify such as title summary owner guidance or starred status while noting that updating user or group arrays will replace the entire existing list rather than adding to it.

Tags > Update tag

This API reference explains how to modify an existing tag’s properties such as title and color by sending a PUT request with JSON data containing the updated values to the specified organization and tag endpoint.

Code Samples > Managing processes (Runs)

The API helps process management by enabling users to launch retrieve update and control the lifecycle of running instances while providing integration capabilities for tasks templates and organizational tags.
Get in touch
About Tallyfy