Skip to main content

​
Overview

The Find Client endpoint allows you to search for a specific client by name within a workspace. This endpoint is designed for Zapier integrations where you need to locate an existing client before performing actions like creating projects or time entries.
This endpoint performs a case-insensitive partial match search on the client name, making it easy to find clients even with slight variations in naming.

​
Authentication

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

​
Find Client

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

​
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 client name to search for. Performs case-insensitive partial matching.Example: "Acme Corporation" or "acme" (will match “Acme Corporation”)

​
Response

​
Success Response

Returns an array containing the matching client object, or an empty array if no match is found: 
[
  {
    "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Acme Corporation",
    "type": "company",
    "status": "active",
    "email": "[email protected]",
    "phone": "+1-800-555-0199",
    "address": "456 Innovation Drive, Silicon Valley, CA 94043",
    "note": "Enterprise client with multiple projects",
    "currency": "USD",
    "created_at": "2024-01-10T10:00:00.000Z",
    "updated_at": "2024-01-12T15:30:00.000Z"
  }
]
​
id
string
Unique client identifier (UUID format)
​
name
string
Client or company name
​
type
string
Client type classification
  • company - Business or organization
  • individual - Individual person
​
status
string
Current client status
  • active - Client is currently active
  • inactive - Client is temporarily inactive
​
email
string
Primary contact email address
​
phone
string
Contact phone number with country code
​
address
string
Complete business or mailing address
​
note
string
Additional notes or comments about the client
​
currency
string
Default currency for client billing (ISO 4217 format)
​
created_at
string
ISO 8601 timestamp when client was created
​
updated_at
string
ISO 8601 timestamp when client was last modified

​
No Results Response

When no matching client 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 client name:
  • Input: "acme" → Matches: “Acme Corporation”, “ACME Inc.”, “acme consulting”
  • Input: "Corp" → Matches: “Acme Corporation”, “Tech Corp”, “Global Corp Ltd”

​
Workspace Scoping

Workspace Isolation: The search is limited to clients associated with the specified workspace. Clients 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 client appears first.

​
Zapier Integration Usage

​
Common Use Cases

Use Case: Allow users to select an existing client when creating projects or time entries in Zapier workflows.Implementation: Use this endpoint to populate dropdown lists or validate client selections.
Use Case: Verify that a client exists before performing operations that require client association.Implementation: Check if the returned array is empty to determine if the client exists.
Use Case: Get complete client details for use in other workflow steps.Implementation: Use the returned client data to populate forms or send notifications.

​
Zapier Field Mapping

When setting up Zapier actions, you can map these client fields:
  • Client ID → id (for referencing in other API calls)
  • Client Name → name (for display purposes)
  • Client Email → email (for notifications)
  • Client Phone → phone (for contact information)
  • Client Address → address (for location-based actions)

​
Best Practices

Search Optimization:
  • Use specific name fragments for better results
  • Consider common abbreviations (e.g., “Corp” for “Corporation”)
  • Handle empty results gracefully in your workflows
  • Cache client data when possible to reduce API calls
Pro Tip: If you need to find multiple clients, consider using the search endpoint instead, which supports pagination and more advanced filtering options.

​
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