Skip to main content

​
Overview

The Find Task endpoint allows you to search for a specific task by name within a workspace. This endpoint returns detailed task information including project details, assignee information, time tracking data, and task status for use in Zapier workflows.
This endpoint supports both GET and POST methods and performs a case-insensitive partial match search on the task name, returning comprehensive task metadata including assignee details and project context.

​
Authentication

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

​
Find Task

​
POST Method

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

​
GET Method

curl -X GET 'https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find?workspace_id=w1b2c3d4-e5f6-7890-abcd-ef0987654321&name=Implement%20user%20authentication' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Request Parameters

​
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 task name to search for. Performs case-insensitive partial matching.Example: "Implement user authentication" or "authentication" (will match “Implement user authentication”)

​
Response

​
Success Response

Returns an array containing the matching task object with comprehensive details, or an empty array if no match is found: 
[
  {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Implement user authentication",
    "description": "Add OAuth2 authentication to the mobile app",
    "status": "in-progress",
    "priority": "high",
    "estimated_hours": 8.0,
    "actual_hours": 4.5,
    "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": "[email protected]",
        "role_name": "Developer"
      }
    ],
    "time_entries_count": 3,
    "created_at": "2024-01-10T10:00:00.000Z",
    "updated_at": "2024-01-12T15:30:00.000Z"
  }
]
​
id
string
Unique task identifier (UUID format)
​
name
string
Task name
​
description
string
Detailed task description
​
status
string
Current task status
  • todo - Task is not yet started
  • in-progress - Task is currently being worked on
  • completed - Task has been finished
​
priority
string
Task priority level
  • low - Low priority task
  • medium - Standard priority task
  • high - High priority task
​
estimated_hours
number
Estimated time to complete the task in hours
​
actual_hours
number
Actual time spent on the task in hours
​
due_date
string
ISO 8601 timestamp of the task due date (null if no due date set)
​
project_id
string
Unique identifier of the project containing this task
​
project_name
string
Name of the project containing this task
​
project_status
string
Current status of the project containing this task
​
workspace_id
string
Unique identifier of the workspace containing this task
​
workspace_name
string
Name of the workspace containing this task
​
client_id
string
Unique identifier of the client associated with the project (null if no client)
​
client_name
string
Name of the client associated with the project (null if no client)
​
assignees
array
Array of team members assigned to this task
​
time_entries_count
integer
Number of time entries logged for this task
​
created_at
string
ISO 8601 timestamp when task was created
​
updated_at
string
ISO 8601 timestamp when task was last modified

​
No Results Response

When no matching task 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 task name:
  • Input: "auth" → Matches: “Implement user authentication”, “Setup auth middleware”, “Test authentication flow”
  • Input: "implement" → Matches: “Implement user authentication”, “Implement payment system”, “Implement API endpoints”

​
Workspace Scoping

Workspace Isolation: The search is limited to tasks within the specified workspace. Tasks 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 task appears first.

​
Task Management Features

​
Status Tracking

Tasks progress through different statuses:
Status: todo
Description: Task is created but not yet started
Use Case: Planning and prioritization phase
Status: in-progress
Description: Task is currently being worked on
Use Case: Active development or work phase
Status: completed
Description: Task has been finished
Use Case: Work completed and ready for review

​
Priority Levels

Tasks can be assigned different priority levels:
  • High Priority (high) - Urgent tasks requiring immediate attention
  • Medium Priority (medium) - Standard tasks with normal priority
  • Low Priority (low) - Tasks that can be completed when time permits

​
Time Tracking

Tasks include comprehensive time tracking information:
  • Estimated Hours - Planned time allocation
  • Actual Hours - Time actually spent on the task
  • Time Entries Count - Number of individual time entries logged

​
Zapier Integration Usage

​
Common Use Cases

Use Case: Allow users to select existing tasks when logging time entries or updating task status in Zapier workflows.Implementation: Use this endpoint to populate dropdown lists or validate task selections.
Use Case: Monitor task progress and status changes for automated notifications or project management workflows.Implementation: Use the status, priority, and due_date fields to track task health and deadlines.
Use Case: Create time entries or generate reports based on task information and time tracking data.Implementation: Use estimated_hours, actual_hours, and time_entries_count for time management workflows.
Use Case: Manage task assignments and notify team members about task updates or new assignments.Implementation: Use the assignees array to identify responsible team members and send notifications.

​
Zapier Field Mapping

When setting up Zapier actions, you can map these task fields:
  • Task ID → id (for referencing in other API calls)
  • Task Name → name (for display purposes)
  • Task Status → status (for conditional logic)
  • Task Priority → priority (for prioritization workflows)
  • Project Information → project_id, project_name (for project association)
  • Client Information → client_id, client_name (for client association)
  • Assignee Information → assignees array (for team member notifications)
  • Time Data → estimated_hours, actual_hours, time_entries_count (for time tracking)

​
Assignment Management

​
Assignee Information

The assignees array provides detailed information about team members assigned to the task:
  • Team Member ID - For referencing in other API calls
  • User Information - Name and email for notifications
  • Role Information - Role name for context and permissions

​
Multi-Assignment Support

Tasks can have multiple assignees, allowing for:
  • Collaborative Work - Multiple team members working on the same task
  • Role-Based Assignment - Different team members with different responsibilities
  • Backup Assignment - Primary and secondary assignees

​
Best Practices

Task Management:
  • Use descriptive, specific task names for better searchability
  • Set realistic estimated hours for better project planning
  • Use priority levels consistently across your workspace
  • Keep task descriptions detailed for better context
  • Regularly update task status to maintain accurate project tracking
Pro Tip: Use the time tracking data (estimated_hours vs actual_hours) to improve future project estimates and identify tasks that consistently take longer than expected.
Due Date Management: Always check if due_date is null before using it in date-based logic, as not all tasks have due dates set.

​
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