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

> Create a new task within a project through the Zapier integration API.

## Overview

Create a new task within a project using the Zapier integration API. This endpoint allows you to add tasks with comprehensive configuration including assignments, priorities, due dates, and time estimates.

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

## Authentication

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

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

## Create Task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://app.timetracker.in/api/integrations/zapier/triggers/tasks' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "name": "Implement user authentication",
      "description": "Add OAuth2 authentication to the mobile app",
      "status": "todo",
      "priority": "high",
      "estimated_hours": 8.0,
      "due_date": "2024-01-15T00:00:00.000Z",
      "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "assignee_ids": "tm1a2b3c4-d5e6-7890-abcd-ef1234567890,tm2b3c4d5-e6f7-8901-bcde-f23456789012"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.timetracker.in/api/integrations/zapier/triggers/tasks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      name: 'Implement user authentication',
      description: 'Add OAuth2 authentication to the mobile app',
      status: 'todo',
      priority: 'high',
      estimated_hours: 8.0,
      due_date: '2024-01-15T00:00:00.000Z',
      project_id: 'p1a2b3c4-d5e6-7890-abcd-ef1234567890',
      assignee_ids: 'tm1a2b3c4-d5e6-7890-abcd-ef1234567890,tm2b3c4d5-e6f7-8901-bcde-f23456789012'
    })
  });

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

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

  url = "https://app.timetracker.in/api/integrations/zapier/triggers/tasks"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
  }
  data = {
      "name": "Implement user authentication",
      "description": "Add OAuth2 authentication to the mobile app",
      "status": "todo",
      "priority": "high",
      "estimated_hours": 8.0,
      "due_date": "2024-01-15T00:00:00.000Z",
      "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "assignee_ids": "tm1a2b3c4-d5e6-7890-abcd-ef1234567890,tm2b3c4d5-e6f7-8901-bcde-f23456789012"
  }

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

### Request Body

<ParamField body="name" type="string" required>
  The name of the task. Must be between 1-255 characters.

  **Example:** `"Implement user authentication"`
</ParamField>

<ParamField body="project_id" type="string" required>
  The UUID of the project where the task will be created.

  **Example:** `"p1a2b3c4-d5e6-7890-abcd-ef1234567890"`
</ParamField>

<ParamField body="description" type="string">
  Optional description of the task. Can be used for detailed task documentation and context.

  **Example:** `"Add OAuth2 authentication to the mobile app"`
</ParamField>

<ParamField body="status" type="string" default="todo">
  The current status of the task. Valid values:

  * `todo` - Task is not yet started
  * `in-progress` - Task is currently being worked on
  * `completed` - Task has been finished

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

<ParamField body="priority" type="string" default="medium">
  The priority level of the task. Valid values:

  * `low` - Low priority task
  * `medium` - Medium priority task
  * `high` - High priority task

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

<ParamField body="estimated_hours" type="number">
  Estimated time to complete the task in hours. Must be a positive number.

  **Example:** `8.0`
</ParamField>

<ParamField body="actual_hours" type="number">
  Actual time spent on the task in hours. Must be a positive number.

  **Example:** `6.5`
</ParamField>

<ParamField body="due_date" type="string">
  When the task is due. Must be a valid ISO 8601 datetime string.

  **Example:** `"2024-01-15T00:00:00.000Z"`
</ParamField>

<ParamField body="assignee_ids" type="string">
  Comma-separated list of team member IDs to assign to the task. Must be valid team member IDs from the project's workspace.

  **Example:** `"tm1a2b3c4-d5e6-7890-abcd-ef1234567890,tm2b3c4d5-e6f7-8901-bcde-f23456789012"`
</ParamField>

## Response

### Success Response

Returns the created task object with all associated data:

```json theme={null}
{
  "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Implement user authentication",
  "description": "Add OAuth2 authentication to the mobile app",
  "status": "todo",
  "priority": "high",
  "estimated_hours": 8.0,
  "actual_hours": null,
  "due_date": "2024-01-15T00:00:00.000Z",
  "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "project_name": "Mobile App Development",
  "project_status": "active",
  "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
  "workspace_name": "Development Team",
  "client_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "client_name": "TechCorp Inc.",
  "assignees": [
    {
      "id": "tm1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "user_id": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "user_name": "John Doe",
      "user_email": "john@example.com",
      "role_name": "Developer"
    },
    {
      "id": "tm2b3c4d5-e6f7-8901-bcde-f23456789012",
      "user_id": "u2b3c4d5-e6f7-8901-bcde-f23456789012",
      "user_name": "Jane Smith",
      "user_email": "jane@example.com",
      "role_name": "Senior Developer"
    }
  ],
  "time_entries_count": 0,
  "created_at": "2024-01-10T10:00:00.000Z",
  "updated_at": "2024-01-10T10:00:00.000Z"
}
```

### Response Fields

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

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

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

<ResponseField name="status" type="string">
  Current task status (`todo`, `in-progress`, or `completed`)
</ResponseField>

<ResponseField name="priority" type="string">
  Task priority level (`low`, `medium`, or `high`)
</ResponseField>

<ResponseField name="estimated_hours" type="number">
  Estimated time to complete the task in hours
</ResponseField>

<ResponseField name="actual_hours" type="number">
  Actual time spent on the task in hours
</ResponseField>

<ResponseField name="due_date" type="string">
  Task due date in ISO 8601 format
</ResponseField>

<ResponseField name="project_id" type="string">
  Associated project identifier
</ResponseField>

<ResponseField name="project_name" type="string">
  Associated project name
</ResponseField>

<ResponseField name="project_status" type="string">
  Associated project status
</ResponseField>

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

<ResponseField name="workspace_name" type="string">
  Associated workspace name
</ResponseField>

<ResponseField name="client_id" type="string">
  Associated client identifier (if project has a client)
</ResponseField>

<ResponseField name="client_name" type="string">
  Associated client name (if project has a client)
</ResponseField>

<ResponseField name="assignees" type="array">
  Array of assigned team members

  <Expandable title="Assignee Object">
    <ResponseField name="id" type="string">
      Team member identifier
    </ResponseField>

    <ResponseField name="user_id" type="string">
      User identifier
    </ResponseField>

    <ResponseField name="user_name" type="string">
      User's full name
    </ResponseField>

    <ResponseField name="user_email" type="string">
      User's email address
    </ResponseField>

    <ResponseField name="role_name" type="string">
      User's role in the workspace
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="time_entries_count" type="integer">
  Total number of time entries associated with this task
</ResponseField>

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

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when task 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="400 Bad Request - Invalid Project">
    ```json theme={null}
    {
      "error": "Project not found"
    }
    ```

    **Cause**: The specified project\_id doesn't exist or you don't have access to it\
    **Solution**: Verify the project ID and ensure it exists in your workspace
  </Accordion>

  <Accordion title="400 Bad Request - Invalid Assignees">
    ```json theme={null}
    {
      "error": "One or more assignee IDs are invalid"
    }
    ```

    **Cause**: One or more team member IDs in assignee\_ids don't exist in the workspace\
    **Solution**: Verify all team member IDs and ensure they belong to the project's workspace
  </Accordion>

  <Accordion title="400 Bad Request - Invalid Hours">
    ```json theme={null}
    {
      "error": "Invalid request body",
      "details": [
        {
          "field": "estimated_hours",
          "message": "Number must be greater than 0"
        }
      ]
    }
    ```

    **Cause**: Hours must be positive numbers\
    **Solution**: Provide valid positive numbers for estimated or actual hours
  </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="500 Internal Server Error">
    ```json theme={null}
    {
      "error": "Internal server error"
    }
    ```

    **Cause**: Server-side error during task 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. **Project Selection**: Use the dynamic dropdown to select the target project
2. **Required Fields**: Only `name` and `project_id` are required
3. **Assignee Selection**: Optionally select team members from the dynamic dropdown
4. **Task Configuration**: Set priority, status, and time estimates
5. **Due Date Management**: Set due dates for task scheduling

### Sample Zapier Usage

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

  <Step title="Action Configuration">
    Configure the "Create Task" action with:

    * **Project**: Select the target project from dropdown
    * **Task Name**: Map from trigger data
    * **Description**: Map from trigger data (if available)
    * **Priority**: Set task priority level
  </Step>

  <Step title="Assignment Setup">
    Configure task assignments:

    * **Assignees**: Select team members from available options
    * **Due Date**: Set task deadline (if applicable)
    * **Estimated Hours**: Set time estimate for planning
  </Step>

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

## Use Cases

<AccordionGroup>
  <Accordion title="Project Management">
    **Automated Task Creation**: Automatically create tasks when projects are created or milestones are reached, ensuring consistent task structure and assignment.
  </Accordion>

  <Accordion title="Issue Tracking">
    **Bug Tracking Integration**: Create tasks automatically when bugs are reported in your issue tracking system, maintaining seamless workflow between bug reports and task management.
  </Accordion>

  <Accordion title="Client Requests">
    **Request Management**: Convert client requests or support tickets into actionable tasks with proper assignments and due dates.
  </Accordion>

  <Accordion title="Team Coordination">
    **Workflow Automation**: Create tasks based on team member availability, project deadlines, or workload distribution for better resource management.
  </Accordion>
</AccordionGroup>

## Important Notes

<Warning>
  **Project Association**: Tasks must be created within an existing project. Ensure the project\_id is valid and accessible in your workspace.
</Warning>

<Info>
  **Assignee Validation**: All assignee IDs must be valid team members in the project's workspace. Invalid IDs will result in a 400 error.
</Info>

<Check>
  **Best Practices**:

  * Use clear, actionable task names that describe the work to be done
  * Set realistic estimated hours for better project planning
  * Assign tasks to appropriate team members based on skills and availability
  * Use due dates to maintain project timelines
  * Provide detailed descriptions for complex tasks
  * Test with sample data before implementing in production
  * Handle error responses gracefully in your application
</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>