Filter contacts
curl --request POST \
--url https://api.reply.io/v3/contacts/filter \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"conditions": [
{
"field": "title",
"and": [
{
"operator": "contains",
"value": "VP"
},
{
"operator": "notContains",
"value": "Assistant"
}
]
},
{
"field": "stage",
"operator": "in",
"value": [
"Interested",
"Meeting booked"
]
},
{
"field": "customFields",
"customFieldKey": "12",
"operator": "greaterThan",
"value": 1000
},
{
"field": "isOptedOut",
"operator": "equals",
"value": false
}
],
"sortBy": "addedOn",
"sortDirection": "desc"
}
'import requests
url = "https://api.reply.io/v3/contacts/filter"
payload = {
"conditions": [
{
"field": "title",
"and": [
{
"operator": "contains",
"value": "VP"
},
{
"operator": "notContains",
"value": "Assistant"
}
]
},
{
"field": "stage",
"operator": "in",
"value": ["Interested", "Meeting booked"]
},
{
"field": "customFields",
"customFieldKey": "12",
"operator": "greaterThan",
"value": 1000
},
{
"field": "isOptedOut",
"operator": "equals",
"value": False
}
],
"sortBy": "addedOn",
"sortDirection": "desc"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
conditions: [
{
field: 'title',
and: [
{operator: 'contains', value: 'VP'},
{operator: 'notContains', value: 'Assistant'}
]
},
{field: 'stage', operator: 'in', value: ['Interested', 'Meeting booked']},
{
field: 'customFields',
customFieldKey: '12',
operator: 'greaterThan',
value: 1000
},
{field: 'isOptedOut', operator: 'equals', value: false}
],
sortBy: 'addedOn',
sortDirection: 'desc'
})
};
fetch('https://api.reply.io/v3/contacts/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reply.io/v3/contacts/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'conditions' => [
[
'field' => 'title',
'and' => [
[
'operator' => 'contains',
'value' => 'VP'
],
[
'operator' => 'notContains',
'value' => 'Assistant'
]
]
],
[
'field' => 'stage',
'operator' => 'in',
'value' => [
'Interested',
'Meeting booked'
]
],
[
'field' => 'customFields',
'customFieldKey' => '12',
'operator' => 'greaterThan',
'value' => 1000
],
[
'field' => 'isOptedOut',
'operator' => 'equals',
'value' => false
]
],
'sortBy' => 'addedOn',
'sortDirection' => 'desc'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reply.io/v3/contacts/filter"
payload := strings.NewReader("{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reply.io/v3/contacts/filter")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reply.io/v3/contacts/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"id": 12345,
"email": "john.doe@company.com",
"firstName": "John",
"lastName": "Doe",
"title": "Senior Product Manager",
"company": "Tech Solutions Inc",
"domain": "company.com",
"companySize": "501-1000",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"timeZoneId": "America/Los_Angeles",
"phone": "+1-415-555-0123",
"phoneStatus": "valid",
"linkedInUrl": "https://www.linkedin.com/in/johndoe",
"linkedInSalesNavigatorUrl": "https://www.linkedin.com/sales/profile/123456",
"linkedInRecruiterUrl": "https://www.linkedin.com/recruiter/profile/789012",
"industry": "Software & Technology",
"notes": "Met at SaaS Conference 2024",
"ownerUserId": 42,
"accountId": 100,
"isOptedOut": false,
"callStatus": "toCall",
"meetingStatus": "none",
"stage": "Interested",
"addingDate": "2024-03-08T10:00:00+00:00",
"createdAt": "2024-03-08T10:00:00",
"lastModifiedAt": "2024-03-10T15:30:00",
"customFields": [
{
"key": "leadSource",
"value": "Conference"
},
{
"key": "budget",
"value": "100k-250k"
}
]
}
],
"hasMore": true
}Contacts
Filter contacts
Breaking change from early November 2026. Send conditions instead of rules, and filter a sequence’s contacts with POST /v3/sequences/{id}/contacts/filter; rules, sequenceId and sequenceStepId return 400.
contacts:read scope (or a broader one that includes it).
Use this endpoint when you need a filtered, sorted page of contacts that a plain email or LinkedIn lookup cannot express. Combine field conditions with optional scoping by list, a free-text search term, and a sort order. Results are paged with the top and skip query parameters. To get only the total for the same criteria, use filter/count. For one sequence’s contacts, use POST /v3/sequences/{id}/contacts/filter.
Conditions are joined with AND, one condition per field: an operator with its value, an and list of rules that must all match, or an or list of alternatives. GET /v3/contacts/filter/fields lists the fields, operators and values your workspace accepts. Field names, operators and enum values are case-insensitive.
POST
/
v3
/
contacts
/
filter
Filter contacts
curl --request POST \
--url https://api.reply.io/v3/contacts/filter \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"conditions": [
{
"field": "title",
"and": [
{
"operator": "contains",
"value": "VP"
},
{
"operator": "notContains",
"value": "Assistant"
}
]
},
{
"field": "stage",
"operator": "in",
"value": [
"Interested",
"Meeting booked"
]
},
{
"field": "customFields",
"customFieldKey": "12",
"operator": "greaterThan",
"value": 1000
},
{
"field": "isOptedOut",
"operator": "equals",
"value": false
}
],
"sortBy": "addedOn",
"sortDirection": "desc"
}
'import requests
url = "https://api.reply.io/v3/contacts/filter"
payload = {
"conditions": [
{
"field": "title",
"and": [
{
"operator": "contains",
"value": "VP"
},
{
"operator": "notContains",
"value": "Assistant"
}
]
},
{
"field": "stage",
"operator": "in",
"value": ["Interested", "Meeting booked"]
},
{
"field": "customFields",
"customFieldKey": "12",
"operator": "greaterThan",
"value": 1000
},
{
"field": "isOptedOut",
"operator": "equals",
"value": False
}
],
"sortBy": "addedOn",
"sortDirection": "desc"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
conditions: [
{
field: 'title',
and: [
{operator: 'contains', value: 'VP'},
{operator: 'notContains', value: 'Assistant'}
]
},
{field: 'stage', operator: 'in', value: ['Interested', 'Meeting booked']},
{
field: 'customFields',
customFieldKey: '12',
operator: 'greaterThan',
value: 1000
},
{field: 'isOptedOut', operator: 'equals', value: false}
],
sortBy: 'addedOn',
sortDirection: 'desc'
})
};
fetch('https://api.reply.io/v3/contacts/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reply.io/v3/contacts/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'conditions' => [
[
'field' => 'title',
'and' => [
[
'operator' => 'contains',
'value' => 'VP'
],
[
'operator' => 'notContains',
'value' => 'Assistant'
]
]
],
[
'field' => 'stage',
'operator' => 'in',
'value' => [
'Interested',
'Meeting booked'
]
],
[
'field' => 'customFields',
'customFieldKey' => '12',
'operator' => 'greaterThan',
'value' => 1000
],
[
'field' => 'isOptedOut',
'operator' => 'equals',
'value' => false
]
],
'sortBy' => 'addedOn',
'sortDirection' => 'desc'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reply.io/v3/contacts/filter"
payload := strings.NewReader("{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reply.io/v3/contacts/filter")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reply.io/v3/contacts/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"conditions\": [\n {\n \"field\": \"title\",\n \"and\": [\n {\n \"operator\": \"contains\",\n \"value\": \"VP\"\n },\n {\n \"operator\": \"notContains\",\n \"value\": \"Assistant\"\n }\n ]\n },\n {\n \"field\": \"stage\",\n \"operator\": \"in\",\n \"value\": [\n \"Interested\",\n \"Meeting booked\"\n ]\n },\n {\n \"field\": \"customFields\",\n \"customFieldKey\": \"12\",\n \"operator\": \"greaterThan\",\n \"value\": 1000\n },\n {\n \"field\": \"isOptedOut\",\n \"operator\": \"equals\",\n \"value\": false\n }\n ],\n \"sortBy\": \"addedOn\",\n \"sortDirection\": \"desc\"\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"id": 12345,
"email": "john.doe@company.com",
"firstName": "John",
"lastName": "Doe",
"title": "Senior Product Manager",
"company": "Tech Solutions Inc",
"domain": "company.com",
"companySize": "501-1000",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"timeZoneId": "America/Los_Angeles",
"phone": "+1-415-555-0123",
"phoneStatus": "valid",
"linkedInUrl": "https://www.linkedin.com/in/johndoe",
"linkedInSalesNavigatorUrl": "https://www.linkedin.com/sales/profile/123456",
"linkedInRecruiterUrl": "https://www.linkedin.com/recruiter/profile/789012",
"industry": "Software & Technology",
"notes": "Met at SaaS Conference 2024",
"ownerUserId": 42,
"accountId": 100,
"isOptedOut": false,
"callStatus": "toCall",
"meetingStatus": "none",
"stage": "Interested",
"addingDate": "2024-03-08T10:00:00+00:00",
"createdAt": "2024-03-08T10:00:00",
"lastModifiedAt": "2024-03-10T15:30:00",
"customFields": [
{
"key": "leadSource",
"value": "Conference"
},
{
"key": "budget",
"value": "100k-250k"
}
]
}
],
"hasMore": true
}Authorizations
Authenticate every request with a Bearer token. Pass your Reply API key in the
Authorization header:
Authorization: Bearer <your-api-key>
Get your API key from the Reply dashboard: Settings → API Key.
Query Parameters
Maximum number of contacts to return (default 100, max 1000)
Number of contacts to skip
Body
application/json
Conditions and scope for filtering contacts.
Field conditions, joined with AND; one condition per field. GET /v3/contacts/filter/fields lists the fields, their operators, value types and allowed values. sequenceIds and sequenceNames both describe the sequences the contact is in, so a filter takes one of them: sequenceIds matches by id, sequenceNames by the whole name (equals) or a fragment of it (contains). and branches take equals, notEquals, contains, notContains, notIn, containsAll, isEmpty and isNotEmpty. Up to 200 branches per condition, 200 values per list and 500 values across all conditions. Omit it, or send null or an empty list, to filter by the other fields only. To filter one sequence's contacts by what happened in that sequence, use POST /v3/sequences/{id}/contacts/filter.
Maximum array length:
20Show child attributes
Show child attributes
Filter by contact list ID.
Free-text search term
Field to sort by. Defaults to addedOn.
Available options:
name, company, email, addedOn, sent, opens, clicks, replies, lastTouch, optedOut, title, country, city, state, deliveryDate, views, domain, companySize, industry, owner, stage, bouncesCount, lastCallDate, callStatus, meetingStatus Sort direction, case-insensitive. Defaults to desc.
Available options:
asc, desc