Skip to main content

​
Overview

Create a new tag in your workspace using the Zapier integration API. Tags are used to categorize and organize time entries, making it easier to track different types of work and generate detailed reports.
This endpoint is designed for Zapier integrations but can be used with any application that needs to create tags programmatically.

​
Authentication

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

​
Create Tag

curl -X POST 'https://app.timetracker.in/api/integrations/zapier/triggers/tags' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "Development",
    "color": "#3B82F6",
    "description": "Tasks related to software development",
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321"
  }'

​
Request Body

​
name
string
required
The name of the tag. Must be between 1-255 characters and unique within the workspace.Example: "Development"
​
workspace_id
string
required
The UUID of the workspace where the tag will be created.Example: "w1b2c3d4-e5f6-7890-abcd-ef0987654321"
​
color
string
The color for the tag. Can be a hex color code (e.g., “#3B82F6”) or a color name (e.g., “blue”).Example: "#3B82F6"
​
description
string
Optional description of the tag. Can be used to provide context about when and how to use the tag.Example: "Tasks related to software development"

​
Response

​
Success Response

Returns the created tag object: 
{
  "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Development",
  "color": "#3B82F6",
  "description": "Tasks related to software development",
  "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

​
Response Fields

​
id
string
Unique tag identifier (UUID format)
​
name
string
Tag name
​
color
string
Tag color (hex code or color name)
​
description
string
Tag description
​
workspace_id
string
Associated workspace identifier
​
created_at
string
ISO 8601 timestamp when tag was created
​
updated_at
string
ISO 8601 timestamp when tag was last modified

​
Error Responses

{
  "error": "Invalid request body",
  "details": [
    {
      "field": "name",
      "message": "String must contain at least 1 character(s)"
    }
  ]
}
Cause: Required fields are missing or invalid
Solution: Check the request body and ensure all required fields are provided with valid values
{
  "error": "Tag already exists",
  "tag": {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Development",
    "color": "#3B82F6",
    "description": "Tasks related to software development",
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
Cause: A tag with the same name already exists in the workspace
Solution: Use a different tag name or check if the existing tag meets your needs
{
  "error": "Unauthorized"
}
Cause: Invalid or missing API key
Solution: Verify your API key is correct and properly formatted
{
  "error": "Workspace not found"
}
Cause: The specified workspace_id doesn’t exist or you don’t have access to it
Solution: Verify the workspace ID and ensure you have proper permissions
{
  "error": "Internal server error"
}
Cause: Server-side error during tag creation
Solution: Retry the request or contact support if the issue persists

​
Zapier Integration

​
Zapier Action Configuration

When using this endpoint in Zapier:
  1. Workspace Selection: Use the dynamic dropdown to select the target workspace
  2. Required Fields: Only name and workspace_id are required
  3. Color Selection: Optionally set a color for visual organization
  4. Description: Add context about the tag’s purpose
  5. Duplicate Handling: Handle cases where tags with the same name already exist

​
Sample Zapier Usage

1

Trigger Setup

Set up a trigger (e.g., new project creation, form submission) that provides tag information
2

Action Configuration

Configure the “Create Tag” action with:
  • Workspace: Select your target workspace
  • Tag Name: Map from trigger data
  • Color: Set a color for the tag (optional)
  • Description: Map from trigger data (if available)
3

Duplicate Handling

Handle potential duplicates:
  • Check if tag already exists before creating
  • Use existing tag if found
  • Create new tag only if needed
4

Test & Activate

Test the Zap with sample data, then activate for live use

​
Use Cases

Automated Tagging: Automatically create tags when new projects are created, ensuring consistent categorization across all time entries.
Activity Classification: Create tags for different types of work (development, design, meetings, etc.) to track how time is spent across projects.
Client-Specific Tags: Create tags for specific clients or project types to better organize and report on client work.
Process Tags: Create tags for different stages of work (planning, development, testing, deployment) to track project progress.

​
Tag Management Best Practices

​
Color Coding

Use consistent color schemes for better visual organization:
  • Blue (#3B82F6): Development work
  • Green (#10B981): Completed tasks
  • Yellow (#F59E0B): In-progress work
  • Red (#EF4444): Urgent or blocked tasks
  • Purple (#8B5CF6): Meetings and collaboration
  • Gray (#6B7280): Administrative tasks

​
Naming Conventions

Follow consistent naming patterns:
  • Work Types: “Development”, “Design”, “Testing”, “Documentation”
  • Project Phases: “Planning”, “Implementation”, “Review”, “Deployment”
  • Client Categories: “Enterprise”, “SMB”, “Internal”
  • Priority Levels: “High Priority”, “Low Priority”, “Rush”

​
Description Guidelines

Provide clear descriptions for tag usage:
  • Purpose: What the tag is used for
  • When to Use: When to apply this tag
  • Examples: Specific examples of work that should use this tag

​
Important Notes

Unique Names: Tag names must be unique within each workspace. Attempting to create a tag with an existing name will result in a 409 conflict error.
Color Formats: Colors can be specified as hex codes (#3B82F6) or color names (blue). The system accepts both formats for flexibility.
Best Practices:
  • Use descriptive, clear tag names that are easy to understand
  • Establish consistent naming conventions across your workspace
  • Use colors strategically for visual organization
  • Provide helpful descriptions for team members
  • Test with sample data before implementing in production
  • Handle duplicate tag scenarios gracefully in your application
  • Consider tag hierarchy for complex categorization needs

​
Rate Limits

  • Rate Limit: 100 requests per minute per API key
  • Burst Limit: 10 requests per second
  • Daily Limit: 10,000 requests per day
Rate limits are applied per API key and workspace combination. Contact support if you need higher limits for your use case.