---
title: "Enhanced contact search with advanced filtering"
description: "Advanced contact search with multiple filtering options and comprehensive criteria"
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.channelautomations.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Channel Automation API › Contacts

`GET /api/contacts/enhanced-search`

Advanced contact search with multiple filtering options and comprehensive criteria

## Authentication

- `ApiKeyAuth`, apiKey, in header, header `X-API-Key`, format `API_KEY`

## Query parameters

- `workspace_id` (`get/api/contacts/enhanced-search.query.workspace_id`; string, required) — Workspace ID for data isolation
- `contact_id` (`get/api/contacts/enhanced-search.query.contact_id`; string, optional) — Search by specific contact UUID
- `phone_number` (`get/api/contacts/enhanced-search.query.phone_number`; string, optional) — Search by phone number
- `lead_status` (`get/api/contacts/enhanced-search.query.lead_status`; string, optional) — Filter by lead status
- `tag` (`get/api/contacts/enhanced-search.query.tag`; string, optional) — Search by tag (JSONB array containment)
- `follow_up_date` (`get/api/contacts/enhanced-search.query.follow_up_date`; string, optional) — Filter by follow-up date (YYYY-MM-DD)
  - format `date`
- `webhook_name` (`get/api/contacts/enhanced-search.query.webhook_name`; string, optional) — Filter by webhook name that created the contact
- `from_date` (`get/api/contacts/enhanced-search.query.from_date`; string, optional) — Filter contacts created from this date (created_at)
  - format `date-time`
- `to_date` (`get/api/contacts/enhanced-search.query.to_date`; string, optional) — Filter contacts created up to this date (created_at)
  - format `date-time`
- `limit` (`get/api/contacts/enhanced-search.query.limit`; integer, optional) — Maximum number of results to return
  - min 1; max 100; default `20`

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.channelautomation.com/api/contacts/enhanced-search?workspace_id=string' \
  --header 'X-API-Key: <X-API-Key>'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/contacts/enhanced-search?workspace_id=string';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/contacts/enhanced-search?workspace_id=string"

headers = {"X-API-Key": "<X-API-Key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Enhanced search results

#### Example

```json
{
  "success": true,
  "contacts": [
    {
      "id": "string",
      "workspace_id": "string",
      "firstname": "John",
      "lastname": "Doe",
      "name": "John Doe",
      "phone_number": "+1234567890",
      "email": "john.doe@example.com",
      "lead_status": "qualified",
      "lead_source": "website",
      "product": "premium_plan",
      "address": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "notes": "string",
      "tags": [
        "vip",
        "enterprise"
      ],
      "priority": "high",
      "opt_in_through": "api",
      "conversation_status": "active",
      "last_message_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "follow_up_date": "2019-08-24",
      "webhook_name": "string",
      "firstName": "string",
      "lastName": "string",
      "phone": "string",
      "workspaceId": "string",
      "status": "string"
    }
  ],
  "total": 0,
  "filters_applied": {},
  "search_stats": {
    "total_filtered": 0,
    "by_status": {},
    "by_source": {},
    "date_range": {}
  }
}
```

- `success` (`get/api/contacts/enhanced-search.response.200.success`; boolean, optional)
  - example `true`
- `contacts` (`get/api/contacts/enhanced-search.response.200.contacts`; array<object>, optional)
  - `firstName` (`get/api/contacts/enhanced-search.response.200.contacts.firstName`; string, required) — The contact's first name
  - `phone` (`get/api/contacts/enhanced-search.response.200.contacts.phone`; string, required) — The contact's phone number
  - `workspaceId` (`get/api/contacts/enhanced-search.response.200.contacts.workspaceId`; string, required) — The workspace ID this contact belongs to
  - `id` (`get/api/contacts/enhanced-search.response.200.contacts.id`; string, optional) — The auto-generated ID of the contact
  - `workspace_id` (`get/api/contacts/enhanced-search.response.200.contacts.workspace_id`; string, optional) — Workspace ID
  - `firstname` (`get/api/contacts/enhanced-search.response.200.contacts.firstname`; string, optional) — Contact's first name
    - example `"John"`
  - `lastname` (`get/api/contacts/enhanced-search.response.200.contacts.lastname`; string, optional) — Contact's last name
    - example `"Doe"`
  - `name` (`get/api/contacts/enhanced-search.response.200.contacts.name`; string, optional) — Full name (auto-generated from firstname + lastname)
    - example `"John Doe"`
  - `phone_number` (`get/api/contacts/enhanced-search.response.200.contacts.phone_number`; string, optional) — Contact's phone number in E.164 format
    - example `"+1234567890"`
  - `email` (`get/api/contacts/enhanced-search.response.200.contacts.email`; string, optional) — The contact's email
    - format `email`; example `"john.doe@example.com"`
  - `lead_status` (`get/api/contacts/enhanced-search.response.200.contacts.lead_status`; string, optional) — Current lead status
    - example `"qualified"`
  - `lead_source` (`get/api/contacts/enhanced-search.response.200.contacts.lead_source`; string, optional) — Source of the lead
    - example `"website"`
  - `product` (`get/api/contacts/enhanced-search.response.200.contacts.product`; string, optional) — Product of interest
    - example `"premium_plan"`
  - `address` (`get/api/contacts/enhanced-search.response.200.contacts.address`; string, optional) — Street address
    - example `"123 Main St"`
  - `city` (`get/api/contacts/enhanced-search.response.200.contacts.city`; string, optional) — City
    - example `"New York"`
  - `state` (`get/api/contacts/enhanced-search.response.200.contacts.state`; string, optional) — State or province
    - example `"NY"`
  - `zip` (`get/api/contacts/enhanced-search.response.200.contacts.zip`; string, optional) — ZIP or postal code
    - example `"10001"`
  - `notes` (`get/api/contacts/enhanced-search.response.200.contacts.notes`; string, optional) — Additional notes about the contact
  - `tags` (`get/api/contacts/enhanced-search.response.200.contacts.tags`; array<string>, optional) — Array of tags associated with contact
    - example `["vip","enterprise"]`
  - `priority` (`get/api/contacts/enhanced-search.response.200.contacts.priority`; string, optional) — Contact priority level
    - one of `"low"`, `"medium"`, `"high"`, `"urgent"`; example `"high"`
  - `opt_in_through` (`get/api/contacts/enhanced-search.response.200.contacts.opt_in_through`; string, optional) — How contact opted in for communications
    - example `"api"`
  - `conversation_status` (`get/api/contacts/enhanced-search.response.200.contacts.conversation_status`; string, optional) — Current conversation status
    - example `"active"`
  - `last_message_at` (`get/api/contacts/enhanced-search.response.200.contacts.last_message_at`; string, optional) — Timestamp of last message
    - format `date-time`
  - `created_at` (`get/api/contacts/enhanced-search.response.200.contacts.created_at`; string, optional) — The date the contact was created
    - format `date-time`
  - `updated_at` (`get/api/contacts/enhanced-search.response.200.contacts.updated_at`; string, optional) — The date the contact was last updated
    - format `date-time`
  - `follow_up_date` (`get/api/contacts/enhanced-search.response.200.contacts.follow_up_date`; string, optional) — Follow-up date
    - format `date`
  - `webhook_name` (`get/api/contacts/enhanced-search.response.200.contacts.webhook_name`; string, optional) — Name of webhook that created this contact
  - `lastName` (`get/api/contacts/enhanced-search.response.200.contacts.lastName`; string, optional) — The contact's last name
  - `status` (`get/api/contacts/enhanced-search.response.200.contacts.status`; string, optional) — The contact's status
- `total` (`get/api/contacts/enhanced-search.response.200.total`; integer, optional) — Total contacts matching criteria
- `filters_applied` (`get/api/contacts/enhanced-search.response.200.filters_applied`; object, optional) — Summary of applied filters
- `search_stats` (`get/api/contacts/enhanced-search.response.200.search_stats`; object, optional)
  - `total_filtered` (`get/api/contacts/enhanced-search.response.200.search_stats.total_filtered`; integer, optional)
  - `by_status` (`get/api/contacts/enhanced-search.response.200.search_stats.by_status`; object, optional)
  - `by_source` (`get/api/contacts/enhanced-search.response.200.search_stats.by_source`; object, optional)
  - `date_range` (`get/api/contacts/enhanced-search.response.200.search_stats.date_range`; object, optional)

### 400

Request validation failed

#### Example

```json
{
  "error": "Validation failed",
  "details": [
    "string"
  ]
}
```

- `error` (`get/api/contacts/enhanced-search.response.400.error`; string, optional)
  - example `"Validation failed"`
- `details` (`get/api/contacts/enhanced-search.response.400.details`; array<string>, optional)

### 401

Authentication required

#### Example

```json
{
  "error": "Authentication required",
  "success": false
}
```

- `error` (`get/api/contacts/enhanced-search.response.401.error`; string, optional)
  - example `"Authentication required"`
- `success` (`get/api/contacts/enhanced-search.response.401.success`; boolean, optional)
  - example `false`

### 500

Internal server error

#### Example

```json
{
  "error": "Internal server error",
  "details": "string",
  "success": false
}
```

- `error` (`get/api/contacts/enhanced-search.response.500.error`; string, optional)
  - example `"Internal server error"`
- `details` (`get/api/contacts/enhanced-search.response.500.details`; string, optional)
- `success` (`get/api/contacts/enhanced-search.response.500.success`; boolean, optional)
  - example `false`


Source: https://developer.channelautomations.com/api/get-api-contacts-enhanced-search/index.md