Search contacts
Search contacts with structured filters, sort, cursor pagination, and field projection. Custom attribute names and value types are returned in data.custom_field_definitions; keys in that map match keys under each contact’s custom_fields object.
POST
/
v1
/
contacts
/
search
Search contacts
curl --request POST \
--url https://api.octolane.com/v1/contacts/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"query": "<string>",
"q": "<string>",
"filters": [
{
"field": "created_at",
"operator": "gt",
"value": "2024-06-11T01:40:00Z"
}
],
"sort": "<string>",
"cursor": "<string>",
"limit": 250,
"fields": [
"<string>"
]
}
'import requests
url = "https://api.octolane.com/v1/contacts/search"
payload = {
"query": "<string>",
"q": "<string>",
"filters": [
{
"field": "created_at",
"operator": "gt",
"value": "2024-06-11T01:40:00Z"
}
],
"sort": "<string>",
"cursor": "<string>",
"limit": 250,
"fields": ["<string>"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
q: '<string>',
filters: [{field: 'created_at', operator: 'gt', value: '2024-06-11T01:40:00Z'}],
sort: '<string>',
cursor: '<string>',
limit: 250,
fields: ['<string>']
})
};
fetch('https://api.octolane.com/v1/contacts/search', 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.octolane.com/v1/contacts/search",
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([
'query' => '<string>',
'q' => '<string>',
'filters' => [
[
'field' => 'created_at',
'operator' => 'gt',
'value' => '2024-06-11T01:40:00Z'
]
],
'sort' => '<string>',
'cursor' => '<string>',
'limit' => 250,
'fields' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.octolane.com/v1/contacts/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.octolane.com/v1/contacts/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.octolane.com/v1/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"data": {
"custom_field_definitions": {
"last_action_date": {
"current_name": "Last Action Date",
"property_name": "custom__last_action_date",
"attribute_type": "date",
"metadata": null
},
"kola": {
"current_name": "Kola",
"property_name": "custom__kola",
"attribute_type": "multi_select",
"metadata": {
"options": [
{
"label": "E",
"value": "e-532837",
"color": "indigo"
}
]
}
}
},
"has_more": true,
"next_cursor": "<string>",
"limit": 123,
"contacts": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"custom_fields": {}
}
]
}
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}Authorizations
Personal API key. Requests act as the workspace member who created the key, with that member's current access, and stop working when the key is disabled or its creator leaves the workspace.
Body
application/json
Search body with optional text query, structured filters, sort, cursor pagination, and field projection.
Maximum array length:
50Show child attributes
Show child attributes
Compact sort expression. Use field, field:asc, or field:desc.
Pattern:
^[^:]+(?::(asc|desc))?$Required range:
1 <= x <= 500Maximum array length:
100Was this page helpful?
⌘I
Search contacts
curl --request POST \
--url https://api.octolane.com/v1/contacts/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"query": "<string>",
"q": "<string>",
"filters": [
{
"field": "created_at",
"operator": "gt",
"value": "2024-06-11T01:40:00Z"
}
],
"sort": "<string>",
"cursor": "<string>",
"limit": 250,
"fields": [
"<string>"
]
}
'import requests
url = "https://api.octolane.com/v1/contacts/search"
payload = {
"query": "<string>",
"q": "<string>",
"filters": [
{
"field": "created_at",
"operator": "gt",
"value": "2024-06-11T01:40:00Z"
}
],
"sort": "<string>",
"cursor": "<string>",
"limit": 250,
"fields": ["<string>"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
q: '<string>',
filters: [{field: 'created_at', operator: 'gt', value: '2024-06-11T01:40:00Z'}],
sort: '<string>',
cursor: '<string>',
limit: 250,
fields: ['<string>']
})
};
fetch('https://api.octolane.com/v1/contacts/search', 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.octolane.com/v1/contacts/search",
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([
'query' => '<string>',
'q' => '<string>',
'filters' => [
[
'field' => 'created_at',
'operator' => 'gt',
'value' => '2024-06-11T01:40:00Z'
]
],
'sort' => '<string>',
'cursor' => '<string>',
'limit' => 250,
'fields' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.octolane.com/v1/contacts/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.octolane.com/v1/contacts/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.octolane.com/v1/contacts/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"q\": \"<string>\",\n \"filters\": [\n {\n \"field\": \"created_at\",\n \"operator\": \"gt\",\n \"value\": \"2024-06-11T01:40:00Z\"\n }\n ],\n \"sort\": \"<string>\",\n \"cursor\": \"<string>\",\n \"limit\": 250,\n \"fields\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"data": {
"custom_field_definitions": {
"last_action_date": {
"current_name": "Last Action Date",
"property_name": "custom__last_action_date",
"attribute_type": "date",
"metadata": null
},
"kola": {
"current_name": "Kola",
"property_name": "custom__kola",
"attribute_type": "multi_select",
"metadata": {
"options": [
{
"label": "E",
"value": "e-532837",
"color": "indigo"
}
]
}
}
},
"has_more": true,
"next_cursor": "<string>",
"limit": 123,
"contacts": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"custom_fields": {}
}
]
}
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}{
"success": false,
"message": "Validation failed",
"statusCode": 400
}