Skip to main content
GET
/
api
/
leads
Get Leads
curl --request GET \
  --url https://octanist.com/api/leads \
  --header 'X-API-KEY: <api-key>'
{
  "success": true,
  "data": [
    {
      "id": "lead_abc123",
      "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",
      "gclid": "abc123",
      "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",
      "li_fat_id": "lifatid123",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "summer_sale",
      "ad_storage": true,
      "ad_user_data": true,
      "analytics_storage": true,
      "ad_personalization": true,
      "googleAdsCampaignId": "123456789",
      "googleAdsCampaignName": "Spring Sale 2026",
      "googleAdsAdGroupId": "987654321",
      "googleAdsAdGroupName": "Brand Keywords",
      "googleAdsAdId": "111222333",
      "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"
  }
}

​
Query Parameters

ParameterTypeRequiredDefaultDescription
limitnumberNo50Results per page (1-100)
pagenumberNo1Page number
sortstringNocreatedAt:descSort field and direction
searchstringNo-Search across name, email, phone
fieldsstringNo-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
?utm_source=google
Multiple values (OR): 
?status=won,lost
Comparison operators: 
?createdAt[gte]=2026-01-01
?createdAt[lte]=2026-03-01
?value[gte]=100
?value[lt]=1000
Existence check: 
?gclid[exists]=true
?fbc[exists]=false

​
Filterable Fields

FieldDescription
statusLead status: open, qualified, won, lost
sourceLead source: inbound, gtm, api, manual, wordpress, import
labelIdLabel ID
valueLead value (supports comparison operators)
websiteWebsite URL
createdAtCreation date (supports comparison/exists operators)
updatedAtLast update date (supports comparison/exists operators)
qualifiedAtQualification date (supports comparison/exists operators)

​
Platform Click IDs

All platform click ID fields support the exists operator.
FieldPlatform
gclidGoogle Ads
ga4cidGoogle Analytics 4 Client ID
ga4sidGoogle Analytics 4 Session ID
fbcMeta (Facebook) Click ID
fbpMeta (Facebook) Browser ID
msclkidMicrosoft Ads
ttclidTikTok
twclidX (Twitter)
rdt_cidReddit
sccidSnapchat
li_fat_idLinkedIn

​
UTM Parameters

FieldDescription
utm_sourceUTM source
utm_mediumUTM medium
utm_campaignUTM campaign

​
Filter Operators

OperatorExampleDescription
(none)?status=wonEquals
[gte]?value[gte]=100Greater than or equal
[gt]?value[gt]=100Greater than
[lte]?value[lte]=1000Less than or equal
[lt]?value[lt]=1000Less than
[exists]?gclid[exists]=trueField is not null / is null

​
Sorting

Sort by any sortable field with direction: 
?sort=createdAt:desc
?sort=value:asc
?sort=updatedAt:desc
Multiple sort fields can be combined with commas: 
?sort=value:desc,createdAt:asc
Sortable fields: createdAt, updatedAt, qualifiedAt, value, name, email, status

​
Field Selection

Request only specific fields to reduce response size: 
?fields=id,name,email,status,value
The id field is always included.

​
Legacy Parameters

For backward compatibility, these legacy parameters are still supported:
LegacyMaps To
updated_afterupdatedAt[gte]
sort=updated_at:descsort=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,name,email,value"

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "lead_abc123",
      "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

StatusCodeDescription
400INVALID_FILTERUnknown or invalid filter field
400INVALID_DATEInvalid date value in a date filter
401UNAUTHORIZEDMissing or invalid API key
500INTERNAL_ERRORServer error

​
Full Lead Object

When no field selection is applied, leads include all available fields: 
{
  "id": "lead_abc123",
  "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",
  "gclid": "abc123",
  "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",
  "li_fat_id": "lifatid123",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "summer_sale",
  "ad_storage": true,
  "ad_user_data": true,
  "analytics_storage": true,
  "ad_personalization": true,
  "googleAdsCampaignId": "123456789",
  "googleAdsCampaignName": "Spring Sale 2026",
  "googleAdsAdGroupId": "987654321",
  "googleAdsAdGroupName": "Brand Keywords",
  "googleAdsAdId": "111222333",
  "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

​
X-API-KEY
string
header
required

API key for authentication

Query Parameters

​
limit
integer
default:50

Results per page (1-100)

Required range: 1 <= x <= 100
​
page
integer
default:1

Page number

Required range: x >= 1
​
sort
string
default:createdAt:desc

Sort field and direction (e.g. createdAt:desc, value:asc). Multiple fields can be combined with commas.

Example:

"createdAt:desc"

​
search
string

Search across name, email, phone

​
fields
string

Comma-separated fields to return. The id field is always included.

Example:

"id,name,email,status,value"

​
status
string

Filter by lead status. Multiple values can be comma-separated.

Example:

"won"

​
source
enum<string>

Filter by lead source

Available options:
inbound,
gtm,
api,
manual,
wordpress,
import
​
labelId
string

Filter by label ID

​
website
string

Filter by website URL

​
utm_source
string

Filter by UTM source

​
utm_medium
string

Filter by UTM medium

​
utm_campaign
string

Filter by UTM campaign

​
updated_after
string<date-time>

Legacy parameter. Maps to updatedAt[gte].

Response

Paginated list of leads

​
success
boolean
Example:

true

​
data
object[]
​
meta
object