Get tag

Endpoint

GET /organizations/{org_id}/tags/{tag_id}

This endpoint retrieves the details for a single tag identified by its unique ID.

Request

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

Headers

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

Query parameters (optional)

• with (string): Include additional related data, e.g., statistics.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const tagId = 'TAG_ID_TO_GET';

const queryParams = '?with=usage_count'; // Example: Include usage stats
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tags/${tagId}${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 tag ${tagId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully retrieved tag ${tagId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error getting tag ${tagId}:`, 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')
tag_id = 'TAG_ID_TO_GET'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tags/{tag_id}'

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

# Optional: Add query parameters
params = {
    'with': 'usage_count' # Example: Include usage statistics
}

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

    tag_data = response.json()
    print(f'Successfully retrieved tag {tag_id}:')
    print(json.dumps(tag_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred getting tag {tag_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 tag {tag_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for tag {tag_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.util.Map;
import java.util.HashMap; // Use HashMap for mutable map
import java.util.stream.Collectors;

public class GetTag {
    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 tagId = "TAG_ID_TO_GET";
        String baseUrl = String.format("https://go.tallyfy.com/api/organizations/%s/tags/%s", orgId, tagId);

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("with", "usage_count");

        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.newHttpClient();
        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 tag " + tagId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON using Jackson/Gson
            } else {
                System.err.println("Failed to get tag " + tagId + ". 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" }
  tagId := "TAG_ID_TO_GET"

  baseUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tags/%s", orgId, tagId)

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

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

  client := &http.Client{Timeout: 10 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
  if err != nil {
    fmt.Printf("Error creating get tag request for tag %s: %v\n", tagId, 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 tag request for tag %s: %v\n", tagId, err)
    return
  }
  defer resp.Body.Close()

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

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

  fmt.Printf("Successfully retrieved tag %s:\n", tagId)
    // 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> GetTallyfyTag(const utility::string_t& tagId)
{
    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("tags"));
    builder.append_path(tagId);
    builder.append_query(U("with"), U("usage_count")); // Example query parameter
    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([tagId](http_response response)
    {
        utility::string_t tagIdW = tagId;
        return response.extract_json().then([response, tagIdW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully retrieved tag " << tagIdW << L":\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")][U("title")].as_string();
                } else {
                    std::wcerr << L"Failed to get tag " << tagIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during get tag: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during get tag response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        GetTallyfyTag(U("TAG_ID_TO_GET")).wait(); // Replace with actual Tag 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 TallyfyTagGetter
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task GetTagAsync(string tagId)
    {
        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"] = "usage_count"; // Example
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/tags/{tagId}?{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 tag {tagId}:");
                // 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 tag {tagId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception getting tag {tagId}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

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

Response

A successful request returns a 200 OK status code and a JSON object containing a data field with the tag’s details.

{
  "data": {
    "id": "TAG_ID_TO_GET",
    "title": "Urgent",
    "color": "#e74c3c",
    "template": 5,
    "active_process": 12,
    "auto_generated": false,
    "created_at": "2023-02-10T10:00:00Z",
    "deleted_at": null,
    // Included if requested with 'with=statistics'
    "statistics": {
      // ... detailed usage counts ...
    }
  }
}

If the tag ID is not found or you lack permission, a 404 Not Found or 403 Forbidden error will be returned.

---

Related articles

Tags > List tags

The GET endpoint allows retrieval of organizational tags with optional filtering and sorting capabilities returning tag details such as ID title color and usage statistics through authenticated API requests.

Groups > Get group

The GET endpoint allows retrieving detailed information about a specific group within an organization using its unique ID through authenticated API requests with code examples in multiple programming languages.

Tasks > Get task

A GET endpoint retrieves detailed task information including status owners deadlines and form fields through unique organization and task IDs with support for optional related data inclusion in multiple programming languages.

Members > Get member

The GET endpoint retrieves detailed profile information of an organization member including their personal details roles permissions and optional related data like stats assets or groups based on the provided user ID.