Update template

Endpoint

PUT /organizations/{org_id}/checklists/{checklist_id}

This endpoint allows you to update the properties of an existing process template (blueprint) identified by its ID.

Request

Replace {org_id} with your Organization ID and {checklist_id} with the ID of the template you want 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 template properties you wish to modify. You only need to include the fields you want to change.

Refer to the #definitions/createChecklistInput schema in the Swagger specification for the full list of updatable properties (it’s often the same or similar to the creation schema). Common fields to update include:

• title (string)
• summary (string)
• owner_id (integer)
• webhook (string)
• guidance (string)
• starred (boolean)
• type (string)
• users (array of integers) - Note: This usually replaces the existing list.
• groups (array of strings) - Note: This usually replaces the existing list.

Example Body (Updating title and summary):

{
  "title": "Updated Template Name",
  "summary": "This template has been updated via the API."
}

Updating Arrays (Users/Groups)

When updating fields like users or groups, the provided array typically replaces the entire existing list of users or groups associated with the template permission, rather than adding to it. Ensure you provide the complete intended list if you modify these.

Code samples

Javascript

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

const updateData = {
  title: "Updated via JS Fetch",
  starred: true, // Example: Star this template
  // summary: "New summary..."
  // Note: Updating 'users' or 'groups' replaces the entire list.
  // users: [1001, 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', // Use PUT for updates
    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 template ${checklistId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully updated template ${checklistId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error updating template ${checklistId}:`, error.message);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
checklist_id = 'TEMPLATE_ID_TO_UPDATE'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/checklists/{checklist_id}'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
}

# Note: Updating 'users' or 'groups' replaces the entire list.
# Fetch current template first if adding/removing incrementally.
update_payload = {
    'summary': 'Updated summary using Python requests.',
    'guidance': 'New guidance notes added.',
    # 'starred': False
    # Add other fields to update here
}

response = None
try:
    response = requests.put(api_url, headers=headers, json=update_payload) # Use PUT and json=
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    updated_template = response.json()
    print(f'Successfully updated template {checklist_id}:')
    print(json.dumps(updated_template, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred updating template {checklist_id}: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed updating template {checklist_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for template update {checklist_id}")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.time.Duration;
// Requires a JSON library like Jackson or Gson
// import com.fasterxml.jackson.databind.ObjectMapper;
// import java.util.Map;
// import java.util.HashMap;

public class UpdateTemplate {

    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String checklistId = "TEMPLATE_ID_TO_UPDATE";
        String apiUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/checklists/" + checklistId;

        // --- Payload Construction ---
        // Using Jackson/Gson recommended:
        /*
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> updateData = new HashMap<>();
        updateData.put("title", "Java Jackson Updated Title");
        updateData.put("starred", false);
        // Note: Updating users/groups replaces the list
        // updateData.put("users", List.of(1001, 1005));
        String jsonPayload;
        try {
            jsonPayload = objectMapper.writeValueAsString(updateData);
        } catch (Exception e) {
            System.err.println("Error creating JSON payload: " + e.getMessage());
            return;
        }
        */
        // Simple manual JSON string:
        String jsonPayload = "{\"title\": \"Java Updated Template Title\", \"starred\": false}";
        // --- End Payload ---

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .header("Content-Type", "application/json")
                .PUT(HttpRequest.BodyPublishers.ofString(jsonPayload)) // Use PUT
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Successfully updated template " + checklistId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON response
            } else {
                System.err.println("Failed to update template " + checklistId + ". Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "os"
  "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
  if accessToken == "" {
    accessToken = "YOUR_PERSONAL_ACCESS_TOKEN"
  }
  orgId := os.Getenv("TALLYFY_ORG_ID")
  if orgId == "" {
    orgId = "YOUR_ORGANIZATION_ID"
  }
  checklistId := "TEMPLATE_ID_TO_UPDATE"
  apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/checklists/%s", orgId, checklistId)

    // Note: Updating users/groups replaces the list
  updateData := map[string]interface{}{
    "title":   "Go Updated Template",
    "summary": "Updated via Go net/http PUT request.",
        // "users": []int{1010, 1012}, // Example: Replaces existing users
  }

  jsonData, err := json.Marshal(updateData)
  if err != nil {
    fmt.Printf("Error marshalling JSON: %v\n", err)
    return
  }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPut, apiUrl, bytes.NewBuffer(jsonData)) // Use http.MethodPut
  if err != nil {
    fmt.Printf("Error creating PUT request: %v\n", err)
    return
  }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")
  req.Header.Set("Content-Type", "application/json")

  resp, err := client.Do(req)
  if err != nil {
    fmt.Printf("Error making PUT request: %v\n", err)
    return
  }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    fmt.Printf("Error reading response body: %v\n", err)
    return
  }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed to update template %s. Status: %d\nBody: %s\n", checklistId, resp.StatusCode, string(body))
    return
  }

  fmt.Printf("Successfully updated template %s:\n", checklistId)
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal response JSON if needed
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> UpdateTallyfyTemplate(const utility::string_t& checklistId, const value& updatePayload)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/checklists/") + checklistId;

    http_client client(apiUrl);
    http_request request(methods::PUT);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));
    request.headers().set_content_type(U("application/json"));
    request.set_body(updatePayload);

    return client.request(request).then([checklistId](http_response response)
    {
        utility::string_t checklistIdW = checklistId;
        return response.extract_json().then([response, checklistIdW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully updated template " << checklistIdW << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to update template " << checklistIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during update template: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during update template response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        value payload = value::object();
        payload[U("title")] = value::string(U("C++ API Updated Template"));
        payload[U("summary")] = value::string(U("Updated summary via C++"));
        payload[U("starred")] = value::boolean(true);
        // Note: Updating users/groups replaces list
        // value users = value::array(); users[0] = value::number(1001); payload[U("users")] = users;

        UpdateTallyfyTemplate(U("TEMPLATE_ID_TO_UPDATE"), payload).wait(); // Replace ID
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization; // For JsonIgnoreCondition
using System.Threading.Tasks;

public class TallyfyTemplateUpdater
{
    private static readonly HttpClient client = new HttpClient();

    public class TemplateUpdatePayload
    {
        // Include only fields you want to update. Use JsonIgnore for optional fields.
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Title { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Summary { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public int? OwnerId { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Webhook { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Guidance { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public bool? Starred { get; set; }
        // Note: Updating Users/Groups REPLACES the existing list.
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<int> Users { get; set; }
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Groups { get; set; }
        // Add other updatable fields from the schema
    }

    public static async Task UpdateTemplateAsync(string checklistId, TemplateUpdatePayload payload)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/checklists/{checklistId}";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Put, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

            // Serialize payload, ignore nulls
            var options = new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
            string jsonPayload = JsonSerializer.Serialize(payload, options);
            request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode) // Expect 200 OK
            {
                Console.WriteLine($"Successfully updated template {checklistId}:");
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody);
                }
            }
            else
            {
                Console.WriteLine($"Failed to update template {checklistId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception updating template {checklistId}: {e.Message}");
        }
         catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     var templateUpdate = new TemplateUpdatePayload {
    //         Summary = "Updated via C#",
    //         Starred = false
    //     };
    //     await UpdateTemplateAsync("TEMPLATE_ID_TO_UPDATE", templateUpdate);
    // }
}

Response

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

{
  "data": {
    "id": "TEMPLATE_ID_TO_UPDATE",
    "title": "Updated via JS Fetch", // Updated title
    "summary": "This template has been updated via the API.", // Original or updated summary
    "starred": true, // Updated value
    // ... other template properties reflecting the current state ...
    "last_updated": "2024-05-20T12:30:00.000Z" // Timestamp reflects the update
  }
}

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

---

Related articles

Processes > Update process

A PUT endpoint that allows updating properties of an existing process run including name summary owner tags folders and form field values while returning the complete updated process data upon success.

Templates > Create a template

A comprehensive POST endpoint for creating organization templates with customizable properties including title summary owner permissions and various configuration options for process management.

Code Samples > Managing templates (blueprints)

API endpoints enable managing process templates through actions like creating retrieving updating publishing exporting and deleting template definitions in an organization.

Templates > Get template

An API endpoint that retrieves detailed information about a specific process template using a GET request with optional parameters to include related data such as steps tags and folder hierarchies.