Get template

Endpoint

GET /organizations/{org_id}/checklists/{checklist_id}

This endpoint retrieves the full details for a single process template (blueprint) identified by its unique ID.

Request

Replace {org_id} with your Organization ID and {checklist_id} with the specific ID of the template you want to retrieve.

Headers

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

Query parameters (optional)

• with (string): A comma-separated list of related data to include (e.g., steps, runs, folder, threads, tags, assets, starredByUsers). Example: with=steps,tags
• version (integer): Retrieve a specific version of the template.
• type (string): Filter by type (e.g., procedure, form).
• entire_folder_tree (string, "0" or "1"): Include the template’s full folder hierarchy.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const checklistId = 'YOUR_TEMPLATE_ID'; // The ID of the template you want

const queryParams = '?with=steps,tags'; // Example: Include steps and tags
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/checklists/${checklistId}${queryParams}`;

const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');

fetch(apiUrl, {
    method: 'GET',
    headers: headers
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to get template ${checklistId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully retrieved template ${checklistId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error getting 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 = 'YOUR_TEMPLATE_ID' # The ID of the template you want
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'
}

# Optional: Add query parameters
params = {
     'with': 'steps,fields', # Example: include steps and kick-off fields
     # 'version': 2 # Example: Get a specific version
}

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

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

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred getting 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 getting template {checklist_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for template {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.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Map;
import java.util.HashMap; // Use HashMap for mutable map
import java.util.stream.Collectors;

public class GetTemplate {

    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 = "YOUR_TEMPLATE_ID"; // The ID of the template you want
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/checklists/" + checklistId;

        // Optional: Build query parameters
        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("with", "steps,tags");
        // queryParamsMap.put("version", "2");

        String queryParamsString = queryParamsMap.entrySet().stream()
            .map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&", "?", ""));

        String apiUrl = baseUrl + (queryParamsMap.isEmpty() ? "" : queryParamsString);

        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")
                .GET()
                .build();

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

            if (response.statusCode() == 200) {
                System.out.println("Successfully retrieved template " + checklistId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing the JSON response using Jackson or Gson
            } else {
                System.err.println("Failed to get 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"
  "net/url"
  "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 := "YOUR_TEMPLATE_ID" // The ID of the template you want

  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/checklists/%s", orgId, checklistId)

  // Optional: Add query parameters
  queryParams := url.Values{}
  queryParams.Set("with", "steps,fields,tags") // Example

  apiUrl := baseURL
  if len(queryParams) > 0 {
    apiUrl += "?" + queryParams.Encode()
  }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
  if err != nil {
    fmt.Printf("Error creating get template request for %s: %v\n", checklistId, err)
    return
  }

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

  resp, err := client.Do(req)
  if err != nil {
    fmt.Printf("Error executing get template request for %s: %v\n", checklistId, err)
    return
  }
  defer resp.Body.Close()

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

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

  fmt.Printf("Successfully retrieved 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 JSON into a struct 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> GetTallyfyTemplate(const utility::string_t& checklistId)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId);
    builder.append_path(U("checklists"));
    builder.append_path(checklistId);
    builder.append_query(U("with"), U("steps,tags")); // Example query parameter
    // builder.append_query(U("version"), 2);
    utility::string_t apiUrl = builder.to_string();

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

    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"));

    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 retrieved template " << checklistIdW << L":\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")][U("title")].as_string();
                } else {
                    std::wcerr << L"Failed to get template " << checklistIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during get template: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during get template response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        GetTallyfyTemplate(U("YOUR_TEMPLATE_ID")).wait(); // Replace with actual Template 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.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;
using System.Web; // For HttpUtility

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

    public static async Task GetTemplateAsync(string checklistId)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";

        // Build URL with query parameters
        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "steps,tags,fields"; // Example
        // query["version"] = "2";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/checklists/{checklistId}?{queryString}";

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

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

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine($"Successfully retrieved template {checklistId}:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                    // Access data: doc.RootElement.GetProperty("data").GetProperty("title").GetString();
                } catch (JsonException) {
                    Console.WriteLine(responseBody); // Print raw if not valid JSON
                }
            }
            else
            {
                Console.WriteLine($"Failed to get template {checklistId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception getting template {checklistId}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await GetTemplateAsync("YOUR_TEMPLATE_ID");
    // }
}

Response

A successful request returns a 200 OK status code and a JSON object containing a data field. The value of data is an object representing the requested template with its full details.

{
  "data": {
    "id": "YOUR_TEMPLATE_ID",
    "title": "Customer Onboarding Process",
    "summary": "Standard process for onboarding new customers.",
    "starred": false,
    "webhook": null,
    "explanation_video": null,
    "guidance": "Detailed guidance notes here.",
    "icon": "fa-users",
    "alias": "customer-onboarding-v2",
    "prerun": [ // Kick-off form fields
      {
        "id": "prerun_field_1",
        "checklist_id": "YOUR_TEMPLATE_ID",
        "alias": "customer_name",
        "field_type": "text",
        // ... other prerun field properties ...
      }
    ],
    "automated_actions": [], // Rules
    "created_by": 1001,
    "owner_id": 1001,
    "created_at": "2023-01-10T10:00:00.000Z",
    "last_updated": "2023-05-15T14:30:00.00Z",
    "archived_at": null,
    "is_public": false,
    // ... many other template properties ...
    // Included if requested via 'with' parameter:
    "steps": [
      {
        "id": "step_1_id",
        "checklist_id": "YOUR_TEMPLATE_ID",
        "alias": "welcome_call",
        "title": "Schedule Welcome Call",
        // ... other step properties ...
      }
      // ... more steps ...
    ],
    "tags": [
        {
            "id": "tag_abc",
            "title": "Onboarding",
            "color": "#3498db"
        }
    ]
  }
}

If the template ID is not found or you don’t have permission, you will likely receive a 404 Not Found or 403 Forbidden error.

---

Related articles

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.

Processes > Get process

An API endpoint that retrieves detailed information about a specific process run through a GET request with optional parameters to include related data like checklists tasks and tags in the response.

Tasks > Get task

A GET endpoint retrieves comprehensive task details including status owners deadlines and form fields through unique organization and task IDs with optional related data parameters.

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.