Get Leads
curl --request GET \
--url https://octanist.com/api/leads \
--header 'X-API-KEY: <api-key>'import requests
url = "https://octanist.com/api/leads"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://octanist.com/api/leads', 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://octanist.com/api/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://octanist.com/api/leads"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://octanist.com/api/leads")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://octanist.com/api/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": [
{
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"status": "won",
"value": 5000,
"note": "Customer notes",
"custom": "{\"company\":\"Acme Inc\"}",
"lossReason": null,
"conversionName": "Purchase",
"source": "gtm",
"website": "https://example.com",
"path": "/pricing",
"referrer": "https://google.com",
"country": "NL",
"gclid": "abc123",
"dclid": "dclid123",
"wbraid": "wbraid123",
"gbraid": "gbraid123",
"ga4cid": "GA1.1.123456789.1234567890",
"ga4sid": "1234567890",
"fbc": "fb.1.1234567890.abc123",
"fbp": "fb.1.1234567890.987654321",
"msclkid": "msclkid123",
"ttclid": "ttclid123",
"twclid": "twclid123",
"rdt_cid": "rdtcid123",
"sccid": "sccid123",
"epik": "epik123",
"li_fat_id": "lifatid123",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"utm_content": "headline_a",
"utm_term": "brand keyword",
"ad_storage": true,
"ad_user_data": true,
"analytics_storage": true,
"ad_personalization": true,
"googleAdsCampaignId": "123456789",
"googleAdsCustomerId": "123-456-7890",
"googleAdsClickDate": "2026-01-15",
"googleAdsCampaignName": "Spring Sale 2026",
"googleAdsAdGroupId": "987654321",
"googleAdsAdGroupName": "Brand Keywords",
"googleAdsAdId": "111222333",
"googleAdsDevice": "DESKTOP",
"googleAdsAdNetworkType": "SEARCH",
"googleAdsClickType": "Headline",
"googleAdsSlot": "Search Top",
"labelId": "label_xyz",
"selectedConversionEventId": "conv_123",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-02-20T14:00:00.000Z",
"qualifiedAt": "2026-01-18T09:00:00.000Z",
"expiresAt": "2026-04-15T10:30:00.000Z"
}
],
"meta": {
"pagination": {
"limit": 50,
"page": 1,
"totalPages": 5,
"total": 234,
"hasMore": true
},
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}Leads
Get Leads
Retrieve a paginated list of leads with optional filtering, sorting, and field selection
GET
/
api
/
leads
Get Leads
curl --request GET \
--url https://octanist.com/api/leads \
--header 'X-API-KEY: <api-key>'import requests
url = "https://octanist.com/api/leads"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://octanist.com/api/leads', 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://octanist.com/api/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://octanist.com/api/leads"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://octanist.com/api/leads")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://octanist.com/api/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": [
{
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"status": "won",
"value": 5000,
"note": "Customer notes",
"custom": "{\"company\":\"Acme Inc\"}",
"lossReason": null,
"conversionName": "Purchase",
"source": "gtm",
"website": "https://example.com",
"path": "/pricing",
"referrer": "https://google.com",
"country": "NL",
"gclid": "abc123",
"dclid": "dclid123",
"wbraid": "wbraid123",
"gbraid": "gbraid123",
"ga4cid": "GA1.1.123456789.1234567890",
"ga4sid": "1234567890",
"fbc": "fb.1.1234567890.abc123",
"fbp": "fb.1.1234567890.987654321",
"msclkid": "msclkid123",
"ttclid": "ttclid123",
"twclid": "twclid123",
"rdt_cid": "rdtcid123",
"sccid": "sccid123",
"epik": "epik123",
"li_fat_id": "lifatid123",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"utm_content": "headline_a",
"utm_term": "brand keyword",
"ad_storage": true,
"ad_user_data": true,
"analytics_storage": true,
"ad_personalization": true,
"googleAdsCampaignId": "123456789",
"googleAdsCustomerId": "123-456-7890",
"googleAdsClickDate": "2026-01-15",
"googleAdsCampaignName": "Spring Sale 2026",
"googleAdsAdGroupId": "987654321",
"googleAdsAdGroupName": "Brand Keywords",
"googleAdsAdId": "111222333",
"googleAdsDevice": "DESKTOP",
"googleAdsAdNetworkType": "SEARCH",
"googleAdsClickType": "Headline",
"googleAdsSlot": "Search Top",
"labelId": "label_xyz",
"selectedConversionEventId": "conv_123",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-02-20T14:00:00.000Z",
"qualifiedAt": "2026-01-18T09:00:00.000Z",
"expiresAt": "2026-04-15T10:30:00.000Z"
}
],
"meta": {
"pagination": {
"limit": 50,
"page": 1,
"totalPages": 5,
"total": 234,
"hasMore": true
},
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human readable error message",
"details": {}
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | number | No | 50 | Results per page (1-100) |
page | number | No | 1 | Page number |
sort | string | No | createdAt:desc | Sort field and direction |
search | string | No | - | Search across external ID, name, email, and phone |
fields | string | No | - | Comma-separated fields to return |
Filtering
Filters can be applied using query parameters. All filters are optional. Simple filters (exact match):?status=won
?source=gtm
?externalId=QUOTE-2026-0042
?utm_source=google
?status=won,lost
?createdAt[gte]=2026-01-01
?createdAt[lte]=2026-03-01
?value[gte]=100
?value[lt]=1000
?gclid[exists]=true
?fbc[exists]=false
Filterable Fields
| Field | Description |
|---|---|
externalId | Customer-owned lead identifier (exact match) |
status | Lead status: open, qualified, won, lost |
source | Lead source: inbound, gtm, api, manual, wordpress, import |
labelId | Label ID |
value | Lead value (supports comparison operators) |
website | Website URL |
createdAt | Creation date (supports comparison/exists operators) |
updatedAt | Last update date (supports comparison/exists operators) |
qualifiedAt | Qualification date (supports comparison/exists operators) |
Platform Click IDs
All platform click ID fields support theexists operator.
| Field | Platform |
|---|---|
gclid | Google Ads |
dclid | Google Display Click ID |
wbraid | Google Ads web-to-app click ID |
gbraid | Google Ads app-to-web click ID |
ga4cid | Google Analytics 4 Client ID |
ga4sid | Google Analytics 4 Session ID |
fbc | Meta (Facebook) Click ID |
fbp | Meta (Facebook) Browser ID |
msclkid | Microsoft Ads |
ttclid | TikTok |
twclid | X (Twitter) |
rdt_cid | |
sccid | Snapchat |
epik | |
li_fat_id |
UTM Parameters
| Field | Description |
|---|---|
utm_source | UTM source |
utm_medium | UTM medium |
utm_campaign | UTM campaign |
Filter Operators
| Operator | Example | Description |
|---|---|---|
| (none) | ?status=won | Equals |
[gte] | ?value[gte]=100 | Greater than or equal |
[gt] | ?value[gt]=100 | Greater than |
[lte] | ?value[lte]=1000 | Less than or equal |
[lt] | ?value[lt]=1000 | Less than |
[exists] | ?gclid[exists]=true | Field is not null / is null |
Sorting
Sort by any sortable field with direction:?sort=createdAt:desc
?sort=value:asc
?sort=updatedAt:desc
?sort=value:desc,createdAt:asc
createdAt, updatedAt, qualifiedAt, value, externalId, name, email, status
Field Selection
Request only specific fields to reduce response size:?fields=id,externalId,name,email,status,value
id field is always included. Supported field names are the fields shown in Full Lead Object.
Legacy Parameters
For backward compatibility, these legacy parameters are still supported:| Legacy | Maps To |
|---|---|
updated_after | updatedAt[gte] |
sort=updated_at:desc | sort=updatedAt:desc |
Example Request
curl -X GET \
-H "X-API-KEY: your_api_key" \
"https://octanist.com/api/leads?status=won&createdAt[gte]=2026-01-01&sort=value:desc&limit=20&fields=id,externalId,name,email,value"
Example Response
{
"success": true,
"data": [
{
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"name": "John Doe",
"email": "john@example.com",
"value": 5000
}
],
"meta": {
"pagination": {
"limit": 20,
"page": 1,
"totalPages": 3,
"total": 45,
"hasMore": true
},
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_FILTER | Unknown or invalid filter field |
| 400 | INVALID_DATE | Invalid date value in a date filter |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 500 | INTERNAL_ERROR | Server error |
Full Lead Object
When no field selection is applied, leads include all available fields:{
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"status": "won",
"value": 5000,
"note": "Customer notes",
"custom": "{\"company\":\"Acme Inc\"}",
"lossReason": null,
"conversionName": "Purchase",
"source": "gtm",
"website": "https://example.com",
"path": "/pricing",
"referrer": "https://google.com",
"country": "NL",
"gclid": "abc123",
"dclid": "dclid123",
"wbraid": "wbraid123",
"gbraid": "gbraid123",
"ga4cid": "GA1.1.123456789.1234567890",
"ga4sid": "1234567890",
"fbc": "fb.1.1234567890.abc123",
"fbp": "fb.1.1234567890.987654321",
"msclkid": "msclkid123",
"ttclid": "ttclid123",
"twclid": "twclid123",
"rdt_cid": "rdtcid123",
"sccid": "sccid123",
"epik": "epik123",
"li_fat_id": "lifatid123",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"utm_content": "headline_a",
"utm_term": "brand keyword",
"ad_storage": true,
"ad_user_data": true,
"analytics_storage": true,
"ad_personalization": true,
"googleAdsCustomerId": "123-456-7890",
"googleAdsClickDate": "2026-01-15",
"googleAdsCampaignId": "123456789",
"googleAdsCampaignName": "Spring Sale 2026",
"googleAdsAdGroupId": "987654321",
"googleAdsAdGroupName": "Brand Keywords",
"googleAdsAdId": "111222333",
"googleAdsDevice": "DESKTOP",
"googleAdsAdNetworkType": "SEARCH",
"googleAdsClickType": "Headline",
"googleAdsSlot": "Search Top",
"labelId": "label_xyz",
"selectedConversionEventId": "conv_123",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-02-20T14:00:00.000Z",
"qualifiedAt": "2026-01-18T09:00:00.000Z",
"expiresAt": "2026-04-15T10:30:00.000Z"
}
Authorizations
API key for authentication
Query Parameters
Results per page (1-100)
Required range:
1 <= x <= 100Page number
Required range:
x >= 1Sort field and direction (e.g. createdAt:desc, value:asc). Multiple fields can be combined with commas.
Example:
"createdAt:desc"
Search across external ID, name, email, and phone
Comma-separated fields to return. The id field is always included.
Example:
"id,externalId,name,email,status,value"
Filter by lead status. Multiple values can be comma-separated.
Example:
"won"
Filter by an exact customer-owned external lead ID
Maximum string length:
255Example:
"QUOTE-2026-0042"
Filter by lead source
Available options:
inbound, gtm, api, manual, wordpress, import Filter by label ID
Filter by website URL
Filter by UTM source
Filter by UTM medium
Filter by UTM campaign
Legacy parameter. Maps to updatedAt[gte].
⌘I