Search contacts

Search contacts by various criteria (ID, phone, email, name) with flexible matching

GET

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

Authorization

ApiKeyAuth
API key in header
required

Query parameters

q
optional
string
General search across name, split first + last name, email, and phone
limit
optional
integer
Maximum number of contacts to return

maximum: 50 · default: 10
id
optional
string
Search by contact UUID (exact match)
phone
optional
string
Search by phone number (partial or exact match)
email
optional
string
Search by email address (exact match)

format: email
firstname
optional
string
Search by first name (partial match, returns up to 10 results)
lastname
optional
string
Search by last name (used with firstname for exact match)

Header parameters

X-Workspace-Id
string
required
Workspace ID for data isolation

Returns

200

Contacts found successfully

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 number of contacts found
search_criteria
optional
object
Applied search criteria

400

Request validation failed

JSON

error
optional
string
details
optional
array of
string

401

Authentication required

JSON

error
optional
string
success
optional
boolean

404

No contacts found

JSON

success
optional
boolean
message
optional
string

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": "[email protected]", "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, "search_criteria": {} }