Skip to main content

​
Overview

The Find Tag endpoint allows you to search for a specific tag by name within a workspace. Tags are used to categorize and organize time entries, making it easier to track different types of work or project phases.
This endpoint performs a case-insensitive partial match search on the tag name and returns tag details including color coding and description for use in Zapier workflows.

​
Authentication

All requests require a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Find Tag

curl -X POST 'https://app.timetracker.in/api/integrations/zapier/triggers/tags/find' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "name": "Development"
  }'

​
Request Body

​
workspace_id
string
required
The unique identifier of the workspace to search within. Must be a valid UUID format.Example: "w1b2c3d4-e5f6-7890-abcd-ef0987654321"
​
name
string
required
The tag name to search for. Performs case-insensitive partial matching.Example: "Development" or "dev" (will match “Development”)

​
Response

​
Success Response

Returns an array containing the matching tag object, or an empty array if no match is found: 
[
  {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Development",
    "color": "#FF6B6B",
    "description": "Tasks related to software development",
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
​
id
string
Unique tag identifier (UUID format)
​
name
string
Tag name used for categorization
​
color
string
Hex color code for visual identification of the tag
​
description
string
Optional description explaining the tag’s purpose or usage
​
workspace_id
string
Unique identifier of the workspace containing this tag
​
created_at
string
ISO 8601 timestamp when tag was created
​
updated_at
string
ISO 8601 timestamp when tag was last modified

​
No Results Response

When no matching tag is found, returns an empty array: 
[]

​
Error Responses

{
  "error": "Invalid request parameters"
}
Cause: Missing required fields or invalid UUID format
Solution: Ensure both workspace_id and name are provided with valid formats
{
  "error": "Unauthorized"
}
Cause: Invalid or missing API key
Solution: Verify your API key is correct and properly formatted
{
  "error": "Internal server error"
}
Cause: Server-side error during search
Solution: Retry the request or contact support if the issue persists

​
Search Behavior

​
Partial Matching

The search performs case-insensitive partial matching on the tag name:
  • Input: "dev" → Matches: “Development”, “DevOps”, “Frontend Dev”
  • Input: "bug" → Matches: “Bug Fix”, “Bug Report”, “Bug Testing”

​
Workspace Scoping

Workspace Isolation: The search is limited to tags within the specified workspace. Tags from other workspaces are not accessible, even if they match the name criteria.

​
Result Ordering

Results are ordered by creation date (newest first), so the most recently created matching tag appears first.

​
Tag Usage and Organization

​
Common Tag Categories

Tags are typically used to categorize work by:
  • Development - Software development tasks
  • Design - UI/UX design work
  • Testing - Quality assurance activities
  • Research - Investigation and analysis
  • Planning - Project planning and setup
  • Implementation - Active development phase
  • Review - Code review and testing
  • Deployment - Release and deployment activities
  • High Priority - Urgent tasks
  • Medium Priority - Standard tasks
  • Low Priority - Non-urgent tasks
  • Client A - Work for specific client
  • Marketing - Marketing department tasks
  • Sales - Sales-related activities

​
Zapier Integration Usage

​
Common Use Cases

Use Case: Allow users to select existing tags when creating time entries or categorizing work in Zapier workflows.Implementation: Use this endpoint to populate dropdown lists or validate tag selections.
Use Case: Automatically categorize time entries based on project type or work category.Implementation: Use tag information to apply appropriate categorization to time entries.
Use Case: Generate reports based on tag usage and time allocation across different categories.Implementation: Use tag data to group and analyze time tracking data.
Use Case: Apply color coding and visual organization to time entries and reports.Implementation: Use the color field to maintain consistent visual organization across systems.

​
Zapier Field Mapping

When setting up Zapier actions, you can map these tag fields:
  • Tag ID → id (for referencing in other API calls)
  • Tag Name → name (for display and categorization)
  • Tag Color → color (for visual organization)
  • Tag Description → description (for context and documentation)
  • Workspace ID → workspace_id (for workspace association)

​
Color Coding

Tags support hex color codes for visual identification:

​
Common Color Schemes

  • Red (#FF6B6B) - High priority or urgent tasks
  • Blue (#3B82F6) - Development or technical work
  • Green (#10B981) - Completed or successful tasks
  • Yellow (#F59E0B) - In-progress or pending tasks
  • Purple (#8B5CF6) - Design or creative work
  • Gray (#6B7280) - Administrative or support tasks

​
Color Usage Best Practices

Visual Organization:
  • Use consistent color schemes across your workspace
  • Consider color accessibility for team members with color vision differences
  • Use colors to quickly identify work types or priorities
  • Maintain color consistency when integrating with external systems

​
Best Practices

Tag Management:
  • Use descriptive, consistent naming conventions
  • Keep tag names concise but clear
  • Use colors to enhance visual organization
  • Regularly review and clean up unused tags
  • Document tag purposes in descriptions
Pro Tip: Create a tag hierarchy or naming convention (e.g., “WorkType:Development”, “Priority:High”) to make searching and organization more systematic.
Tag Limits: While there’s no hard limit on the number of tags, consider keeping the total number manageable to avoid overwhelming users in dropdown lists and interfaces.

​
Rate Limits

This endpoint follows standard API rate limiting:
  • Rate Limit: 100 requests per minute per API key
  • Burst Limit: 10 requests per second
  • Reset Period: Rolling 60-second window
Rate Limit Headers: Response headers include current usage information:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Timestamp when the limit resets