> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timetracker.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Tag

> Create a new tag in your workspace through the Zapier integration API.

## 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.

<Note>
  This endpoint is designed for Zapier integrations but can be used with any application that needs to create tags programmatically.
</Note>

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Create Tag

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.timetracker.in/api/integrations/zapier/triggers/tags', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      name: 'Development',
      color: '#3B82F6',
      description: 'Tasks related to software development',
      workspace_id: 'w1b2c3d4-e5f6-7890-abcd-ef0987654321'
    })
  });

  const tag = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.timetracker.in/api/integrations/zapier/triggers/tags"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
  }
  data = {
      "name": "Development",
      "color": "#3B82F6",
      "description": "Tasks related to software development",
      "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321"
  }

  response = requests.post(url, headers=headers, json=data)
  tag = response.json()
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  The name of the tag. Must be between 1-255 characters and unique within the workspace.

  **Example:** `"Development"`
</ParamField>

<ParamField body="workspace_id" type="string" required>
  The UUID of the workspace where the tag will be created.

  **Example:** `"w1b2c3d4-e5f6-7890-abcd-ef0987654321"`
</ParamField>

<ParamField body="color" type="string">
  The color for the tag. Can be a hex color code (e.g., "#3B82F6") or a color name (e.g., "blue").

  **Example:** `"#3B82F6"`
</ParamField>

<ParamField body="description" type="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"`
</ParamField>

## Response

### Success Response

Returns the created tag object:

```json theme={null}
{
  "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

<ResponseField name="id" type="string">
  Unique tag identifier (UUID format)
</ResponseField>

<ResponseField name="name" type="string">
  Tag name
</ResponseField>

<ResponseField name="color" type="string">
  Tag color (hex code or color name)
</ResponseField>

<ResponseField name="description" type="string">
  Tag description
</ResponseField>

<ResponseField name="workspace_id" type="string">
  Associated workspace identifier
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when tag was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when tag was last modified
</ResponseField>

### Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Validation Error">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="409 Conflict - Duplicate Tag">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Unauthorized"
    }
    ```

    **Cause**: Invalid or missing API key\
    **Solution**: Verify your API key is correct and properly formatted
  </Accordion>

  <Accordion title="404 Not Found - Workspace">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={null}
    {
      "error": "Internal server error"
    }
    ```

    **Cause**: Server-side error during tag creation\
    **Solution**: Retry the request or contact support if the issue persists
  </Accordion>
</AccordionGroup>

## 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

<Steps>
  <Step title="Trigger Setup">
    Set up a trigger (e.g., new project creation, form submission) that provides tag information
  </Step>

  <Step title="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)
  </Step>

  <Step title="Duplicate Handling">
    Handle potential duplicates:

    * Check if tag already exists before creating
    * Use existing tag if found
    * Create new tag only if needed
  </Step>

  <Step title="Test & Activate">
    Test the Zap with sample data, then activate for live use
  </Step>
</Steps>

## Use Cases

<AccordionGroup>
  <Accordion title="Project Categorization">
    **Automated Tagging**: Automatically create tags when new projects are created, ensuring consistent categorization across all time entries.
  </Accordion>

  <Accordion title="Work Type Tracking">
    **Activity Classification**: Create tags for different types of work (development, design, meetings, etc.) to track how time is spent across projects.
  </Accordion>

  <Accordion title="Client Organization">
    **Client-Specific Tags**: Create tags for specific clients or project types to better organize and report on client work.
  </Accordion>

  <Accordion title="Team Workflow">
    **Process Tags**: Create tags for different stages of work (planning, development, testing, deployment) to track project progress.
  </Accordion>
</AccordionGroup>

## 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

<Warning>
  **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.
</Warning>

<Info>
  **Color Formats**: Colors can be specified as hex codes (#3B82F6) or color names (blue). The system accepts both formats for flexibility.
</Info>

<Check>
  **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
</Check>

## Rate Limits

* **Rate Limit**: 100 requests per minute per API key
* **Burst Limit**: 10 requests per second
* **Daily Limit**: 10,000 requests per day

<Note>
  Rate limits are applied per API key and workspace combination. Contact support if you need higher limits for your use case.
</Note>