Skip to content

Update process

Endpoint

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

This endpoint allows you to update certain properties of an existing 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": "2024-05-21T22:00:00Z", // 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

Updates existing tasks by modifying properties like title description deadline assignees and form field values through a PUT request to the Tallyfy API endpoint.

Tags > Update tag

The PUT endpoint enables updating an existing tag’s properties like title and color within an organization by sending a JSON request with the new values and receiving the updated tag details in response.