Create a template

This endpoint allows you to create a new template (also known as a blueprint) within a specified organization.

Endpoint

POST https://go.tallyfy.com/api/organizations/{org}/checklists

Path Parameters

Parameter	Type	Description
org	string	Required. The ID of the organization.

Body Parameters

The request body should be a JSON object containing the desired properties for the new template.

Parameter	Type	Description
title	string	Required. The title of the template.
summary	string	A brief summary or description of the template.
owner_id	integer	The ID of the member who will own the template.
webhook	string	A URL to send webhook notifications to for template events.
explanation_video	string	URL of a video explaining the template.
starred	boolean	Whether the template should be starred by default.
guidance	string	Detailed guidance or instructions for using the template.
icon	string	Name of an icon to associate with the template.
is_public	boolean	Whether the template should be publicly accessible in the library.
is_featured	boolean	Whether the template should be featured in the public library.
public_cover	string	URL for a cover image for the public library listing.
type	string	The type of template (e.g., procedure, form, document).
default_process_name_format	string	A format string for automatically naming processes launched from this template (uses variables).
is_public_kickoff	boolean	Whether the kick-off form for this template is public.
auto_naming	boolean	Enable or disable automatic naming of processes launched from this template based on the format string.
users	array	An array of member IDs who have default access permissions to this template.
groups	array	An array of group IDs that have default access permissions to this template.
prerun	array	An array of objects defining kick-off form fields for the template. See swagger.json for structure.
folderize_process	boolean	Automatically create a folder for processes launched from this template.
tag_process	boolean	Automatically tag processes launched from this template.
allow_launcher_change_name	boolean	Whether the user launching a process can override the default process name.
ko_form_blueprint_id	string	ID of another template to use as the kick-off form.
default_folder	string	The ID of the folder where processes launched from this template should be placed by default.
folder_changeable_by_launcher	boolean	Whether the user launching a process can change the default folder.
kickoff_sharing_user_id	integer	The ID of the user whose sharing settings should be used for the public kick-off form.

Code Samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID'; // Replace with actual Org ID
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/checklists`;

const templateData = {
    title: "New JS API Template", // Required
    summary: "Template created via Fetch API.",
    owner_id: 12345, // Optional: Specify owner User ID
    type: "procedure" // Or "form", "document"
    // Add other optional fields like prerun, users, groups, etc. as needed
};

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(templateData)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to create template:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
         // Expect 200 OK or 201 Created
        console.log(`Template creation initiated. Status: ${response.status}`);
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully created template:');
    console.log(JSON.stringify(data, null, 2));
    // Use data.data.id to get the new template ID
})
.catch(error => {
    console.error('Error creating template:', 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') # Replace with actual Org ID
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/checklists'

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

template_payload = {
    'title': 'New Python API Template', # Required
    'summary': 'Template created via Python requests.',
    'owner_id': 12345, # Optional: Specify owner User ID
    'type': 'procedure',
    # Example: Add default users with access
    # 'users': [1001, 1005]
}

response = None
try:
    response = requests.post(api_url, headers=headers, json=template_payload)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    created_template = response.json()
    print('Successfully created template:')
    print(json.dumps(created_template, indent=4))
    # new_template_id = created_template.get('data', {}).get('id')

except requests.exceptions.HTTPError as http_err:
    error_details = ""
    try:
        if response is not None:
             error_details = response.json()
    except json.JSONDecodeError:
        if response is not None:
             error_details = response.text
    print(f"HTTP error occurred creating template: {http_err}")
    print(f"Response Body: {error_details}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed creating template: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode successful JSON response after creating template")
    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 CreateTemplate {
    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"); // Replace with actual Org ID
        String apiUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/checklists";

        // --- Payload Construction ---
        // Using Jackson/Gson recommended:
        /*
        ObjectMapper mapper = new ObjectMapper();
        Map<String, Object> templateData = new HashMap<>();
        templateData.put("title", "Java API Template"); // Required
        templateData.put("summary", "Created via Java");
        templateData.put("type", "procedure");
        String jsonPayload;
        try {
            jsonPayload = mapper.writeValueAsString(templateData);
        } catch (Exception e) {
            System.err.println("Failed to serialize JSON: " + e.getMessage());
            return;
        }
        */
        // Simple manual JSON string:
        String jsonPayload = "{\"title\": \"Java API Template Simple\", \"type\": \"procedure\"}"; // Minimal payload
        // --- 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")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

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

            if (response.statusCode() == 200 || response.statusCode() == 201) { // API might return 201 Created
                System.out.println("Successfully created template:");
                System.out.println(response.body());
                // TODO: Consider parsing the JSON response
                // String templateId = objectMapper.readTree(response.body()).path("data").path("id").asText();
            } else {
                System.err.println("Failed to create template. 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" } // Replace with actual Org ID
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/checklists", orgId)

  templateData := map[string]interface{}{
    "title": "Go API Template", // Required
        "summary": "Created via Go net/http",
        "type": "procedure",
        // "owner_id": 12345,
        // "users": []int{1001},
  }

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

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPost, apiUrl, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Printf("Error creating create template 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 executing create template request: %v\n", err)
        return
    }
  defer resp.Body.Close()

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

    // API might return 201 Created
  if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
    fmt.Printf("Failed to create template. Status: %d\nBody: %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Println("Successfully created template:")
    // 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 JSON to get the new template ID etc.
}

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> CreateTallyfyTemplate(const value& templatePayload)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID"); // Replace with actual Org ID
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/checklists");

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

    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(templatePayload);

    return client.request(request).then([](http_response response)
    {
        return response.extract_json().then([response](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                // API might return 201 Created
                if (response.status_code() == status_codes::OK || response.status_code() == status_codes::Created) {
                    std::wcout << L"Successfully created template:\n" << body.serialize() << std::endl;
                    // Extract new template ID: body[U("data")][U("id")].as_string();
                } else {
                    std::wcerr << L"Failed to create template. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during create template: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during create template response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        value payload = value::object();
        payload[U("title")] = value::string(U("C++ API Template")); // Required
        payload[U("summary")] = value::string(U("Created via C++ REST SDK"));
        payload[U("type")] = value::string(U("procedure"));
        // payload[U("owner_id")] = value::number(12345);

        CreateTallyfyTemplate(payload).wait();
    } 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 TallyfyTemplateCreator
{
    private static readonly HttpClient client = new HttpClient();

    public class TemplatePayload
    {
        public string Title { get; set; } // Required

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Summary { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public int? OwnerId { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Type { get; set; } // e.g., "procedure"

        // Add other properties from the Body Parameters table as needed
        // [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        // public List<int> Users { get; set; }
        // ... etc ...
    }

    public static async Task CreateTemplateAsync(TemplatePayload payload)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID"; // Replace with actual Org ID
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/checklists";

        if (string.IsNullOrWhiteSpace(payload?.Title)) {
            Console.WriteLine("Error: Template Title is required.");
            return;
        }

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Post, 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) // Check for 200 OK or 201 Created
            {
                Console.WriteLine("Successfully created template:");
                 try {
                     using var doc = JsonDocument.Parse(responseBody);
                     Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                     // Get template ID: doc.RootElement.GetProperty("data").GetProperty("id").GetString();
                 } catch (JsonException) {
                     Console.WriteLine(responseBody);
                 }
            }
            else
            {
                Console.WriteLine($"Failed to create template. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception: {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 newTemplate = new TemplatePayload {
    //         Title = "C# API Template Example",
    //         Summary = "Created from C#",
    //         Type = "procedure"
    //     };
    //     await CreateTemplateAsync(newTemplate);
    // }
}

Example Response (200 OK)

{
  "data": {
    "id": "b3d9c1a8e7f6...", // Unique ID of the newly created template
    "title": "New Client Onboarding Template",
    "summary": "Standard procedure for onboarding new clients.",
    "starred": false,
    "webhook": null,
    "explanation_video": null,
    "guidance": null,
    "icon": null,
    "alias": "new-client-onboarding-template-b3d9c1", // Auto-generated alias
    "prerun": [], // Empty array as no kick-off fields were defined
    "automated_actions": [],
    "created_by": 123, // ID of the user who made the API call
    "owner_id": 12345,
    "started_processes": 0,
    "kickoff_title": null,
    "kickoff_description": null,
    "created_at": "2023-10-27T10:00:00.000Z",
    "last_updated": "2023-10-27T10:00:00.000Z",
    "archived_at": null,
    "is_public": false,
    "is_featured": false,
    "users": [],
    "groups": [],
    "public_cover": null,
    "industry_tags": [],
    "topic_tags": [],
    "type": "procedure",
    "default_process_name_format": null,
    "is_public_kickoff": false,
    "dual_version_enabled": false,
    "is_published_state": false, // Templates are created in draft state
    "auto_naming": false,
    "last_updated_by": 123,
    "linked_tasks": [],
    "folderize_process": false,
    "tag_process": false,
    "allow_launcher_change_name": false,
    "is_pinned": false,
    "ko_form_blueprint_id": null,
    "default_folder": null,
    "folder_changeable_by_launcher": false,
    "kickoff_sharing_user_id": null
    // ... other template properties with default values
  }
}

Related articles

Templates > Update template

Modify the details of an existing process template (blueprint).

Templates > List templates

An API endpoint documentation for retrieving process templates from organizations with code examples in JavaScript Python Java and Go along with details about request headers query parameters and response format.

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.

Processes > Launch process

A comprehensive REST API endpoint that enables launching new process instances by sending a POST request with required template ID and name along with optional configurations for pre-filling fields and overriding task properties.