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 (fetch)

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 // Let's star this template
};

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 => {
    if (!response.ok) {
        return response.json().then(errData => {
            throw new Error(`HTTP error! status: ${response.status}, message: ${JSON.stringify(errData)}`);
        }).catch(() => {
             throw new Error(`HTTP error! status: ${response.status}`);
        });
    }
    return response.json();
})
.then(data => {
    console.log(`Successfully updated template ${checklistId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error updating template:', error);
});

Python (requests)

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'
}

update_payload = {
    'summary': 'Updated summary using Python requests.',
    'guidance': 'New guidance notes added.'
    # Add other fields to update here
}

try:
    response = requests.put(api_url, headers=headers, json=update_payload) # Use PUT and json=
    response.raise_for_status()

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

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
    if response is not None:
        print(f"Response Status: {response.status_code}")
        try:
            print(f"Response Body: {response.json()}")
        except json.JSONDecodeError:
            print(f"Response Body: {response.text}")

Java (HttpClient)

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;
// Assumes JSON library like Jackson or Gson
// import com.fasterxml.jackson.databind.ObjectMapper;

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;

        // Simple String JSON payload. Use a Map/POJO and library for complex updates.
        String jsonPayload = "{\"title\": \"Java Updated Template Title\", \"starred\": false}";

        // Example using Jackson ObjectMapper:
        // ObjectMapper objectMapper = new ObjectMapper();
        // Map<String, Object> updateData = new HashMap<>();
        // updateData.put("title", "Java Jackson Updated Title");
        // updateData.put("starred", false);
        // try {
        //     jsonPayload = objectMapper.writeValueAsString(updateData);
        // } catch (JsonProcessingException e) {
        //     System.err.println("Error creating JSON payload: " + e.getMessage());
        //     return;
        // }

        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: Parse JSON response
            } else {
                System.err.println("Failed to update template. Status: " + response.statusCode());
                System.err.println("Response: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        }
    }
}

Go (net/http)

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)

  updateData := map[string]interface{}{
    "title":   "Go Updated Template",
    "summary": "Updated via Go net/http PUT request.",
  }

  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)
  fmt.Println(string(body))
  // TODO: Unmarshal response JSON if needed
}

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

Templates > Get template

Fetch the current details of this template.

Templates > Archive/Delete template

Learn how to archive or delete this template.

Templates > List templates

See all available templates.