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

# Find Client

> Search for a specific client by name within a workspace using advanced filtering options.

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

<Note>
  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.
</Note>

## Authentication

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

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

## Find Client

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.timetracker.in/api/integrations/zapier/triggers/clients/find', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      workspace_id: 'w1b2c3d4-e5f6-7890-abcd-ef0987654321',
      name: 'Acme Corporation'
    })
  });

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

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

  url = "https://app.timetracker.in/api/integrations/zapier/triggers/clients/find"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
  }
  data = {
      "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
      "name": "Acme Corporation"
  }

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

### Request Body

<ParamField body="workspace_id" type="string" required>
  The unique identifier of the workspace to search within. Must be a valid UUID format.

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

<ParamField body="name" type="string" required>
  The client name to search for. Performs case-insensitive partial matching.

  **Example:** `"Acme Corporation"` or `"acme"` (will match "Acme Corporation")
</ParamField>

## Response

### Success Response

Returns an array containing the matching client object, or an empty array if no match is found:

```json theme={null}
[
  {
    "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Acme Corporation",
    "type": "company",
    "status": "active",
    "email": "info@acmecorp.com",
    "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"
  }
]
```

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

<ResponseField name="name" type="string">
  Client or company name
</ResponseField>

<ResponseField name="type" type="string">
  Client type classification

  * `company` - Business or organization
  * `individual` - Individual person
</ResponseField>

<ResponseField name="status" type="string">
  Current client status

  * `active` - Client is currently active
  * `inactive` - Client is temporarily inactive
</ResponseField>

<ResponseField name="email" type="string">
  Primary contact email address
</ResponseField>

<ResponseField name="phone" type="string">
  Contact phone number with country code
</ResponseField>

<ResponseField name="address" type="string">
  Complete business or mailing address
</ResponseField>

<ResponseField name="note" type="string">
  Additional notes or comments about the client
</ResponseField>

<ResponseField name="currency" type="string">
  Default currency for client billing (ISO 4217 format)
</ResponseField>

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

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

### No Results Response

When no matching client is found, returns an empty array:

```json theme={null}
[]
```

### Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Invalid Parameters">
    ```json theme={null}
    {
      "error": "Invalid request parameters"
    }
    ```

    **Cause**: Missing required fields or invalid UUID format\
    **Solution**: Ensure both `workspace_id` and `name` are provided with valid formats
  </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 search\
    **Solution**: Retry the request or contact support if the issue persists
  </Accordion>
</AccordionGroup>

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

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

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

<AccordionGroup>
  <Accordion title="Client Selection in Workflows">
    **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.
  </Accordion>

  <Accordion title="Data Validation">
    **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.
  </Accordion>

  <Accordion title="Client Information Retrieval">
    **Use Case**: Get complete client details for use in other workflow steps.

    **Implementation**: Use the returned client data to populate forms or send notifications.
  </Accordion>
</AccordionGroup>

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

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

<Tip>
  **Pro Tip**: If you need to find multiple clients, consider using the search endpoint instead, which supports pagination and more advanced filtering options.
</Tip>

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

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