The search endpoint lets you look up contacts by their channel identifiers — phone numbers, email addresses, or other channel values — without knowing their Heymarket IDs. You can search for multiple identifiers in a single request.
POST /v2/contacts/search
Returns all contacts that match the provided channel identifiers.
Request body
Array of channel filter objects. Each object specifies a channel type and a list of values to search for.
channel_type — the type of channel to search: phone, email, facebook, or another supported integration. Optional — if omitted, Heymarket auto-detects the type from the format of the values.channel_ids — array of channel values to search for, such as phone numbers or email addresses.
If you omit channel_type, Heymarket automatically detects it from the format of each value: E.164-format strings are treated as phone numbers, and strings containing @ are treated as email addresses.
Response
Returns an array of Contact objects matching the provided channel identifiers.
Examples
Search by phone
Search by email
Auto-detected type
curl -X POST https://api.heymarket.com/v2/contacts/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_channels": [
{
"channel_type": "phone",
"channel_ids": ["14155551234", "14155559876"]
}
]
}'
curl -X POST https://api.heymarket.com/v2/contacts/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_channels": [
{
"channel_type": "email",
"channel_ids": ["alice@example.com", "bob@example.com"]
}
]
}'
curl -X POST https://api.heymarket.com/v2/contacts/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_channels": [
{
"channel_ids": ["14155551234"]
}
]
}'
[
{
"id": 98765,
"display_name": "Alice Smith",
"first": "Alice",
"last": "Smith",
"phone": "14155551234",
"email": "alice@example.com",
"is_opted_out": false
}
]
