Enhanced contact search with advanced filtering

Advanced contact search with multiple filtering options and comprehensive criteria

GET

https://api.channelautomation.com/api/contacts/enhanced-search

Authorization

ApiKeyAuth
API key in header
required

Query parameters

workspace_id
string
required
Workspace ID for data isolation
contact_id
optional
string
Search by specific contact UUID
phone_number
optional
string
Search by phone number
lead_status
optional
string
Filter by lead status
tag
optional
string
Search by tag (JSONB array containment)
follow_up_date
optional
string
Filter by follow-up date (YYYY-MM-DD)

format: date
webhook_name
optional
string
Filter by webhook name that created the contact
from_date
optional
string
Filter contacts created from this date (created_at)

format: date-time
to_date
optional
string
Filter contacts created up to this date (created_at)

format: date-time
limit
optional
integer
Maximum number of results to return

maximum: 100 · minimum: 1 · default: 20

Returns

200

Enhanced search results

JSON

success
optional
boolean
contacts
optional
array of
object
- firstName
  string
  required
  The contact's first name
- phone
  string
  required
  The contact's phone number
- workspaceId
  string
  required
  The workspace ID this contact belongs to
- id
  optional
  string
  The auto-generated ID of the contact
- workspace_id
  optional
  string
  Workspace ID
- firstname
  optional
  string
  Contact's first name
- lastname
  optional
  string
  Contact's last name
- name
  optional
  string
  Full name (auto-generated from firstname + lastname)
- phone_number
  optional
  string
  Contact's phone number in E.164 format
- email
  optional
  string
  The contact's email
  
  format: email
- lead_status
  optional
  string
  Current lead status
- lead_source
  optional
  string
  Source of the lead
- product
  optional
  string
  Product of interest
- address
  optional
  string
  Street address
- city
  optional
  string
  City
- state
  optional
  string
  State or province
- zip
  optional
  string
  ZIP or postal code
- notes
  optional
  string
  Additional notes about the contact
- tags
  optional
  array of
  string
  Array of tags associated with contact
- priority
  optional
  low
  or
  medium
  or
  high
  or
  urgent
  Contact priority level
- opt_in_through
  optional
  string
  How contact opted in for communications
- conversation_status
  optional
  string
  Current conversation status
- last_message_at
  optional
  string
  Timestamp of last message
  
  format: date-time
- created_at
  optional
  string
  The date the contact was created
  
  format: date-time
- updated_at
  optional
  string
  The date the contact was last updated
  
  format: date-time
- follow_up_date
  optional
  string
  Follow-up date
  
  format: date
- webhook_name
  optional
  string
  Name of webhook that created this contact
- lastName
  optional
  string
  The contact's last name
- status
  optional
  string
  The contact's status
}
total
optional
integer
Total contacts matching criteria
filters_applied
optional
object
Summary of applied filters
search_stats
optional
object
- total_filtered
  optional
  integer
- by_status
  optional
  object
- by_source
  optional
  object
- date_range
  optional
  object
}

400

Request validation failed

JSON

error
optional
string
details
optional
array of
string

401

Authentication required

JSON

error
optional
string
success
optional
boolean

500

Internal server error

JSON

error
optional
string
details
optional
string
success
optional
boolean

{ "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": {} } }