Get Leads - Docs Octanist

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",
      "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"
  }
}

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",
      "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"
  }
}

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 name, email, 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
?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

Field	Description
`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 the exists 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`	Reddit
`sccid`	Snapchat
`epik`	Pinterest
`li_fat_id`	LinkedIn

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

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. 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,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

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",
  "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

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"

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[]

Show child attributes

​Query Parameters

​Filtering

​Filterable Fields

​Platform Click IDs

​UTM Parameters

​Filter Operators

​Sorting

​Field Selection

​Legacy Parameters

​Example Request

​Example Response

​Error Responses

​Full Lead Object

Authorizations

Query Parameters

Response

Query Parameters

Filtering

Filterable Fields

Platform Click IDs

UTM Parameters

Filter Operators

Sorting

Field Selection

Legacy Parameters

Example Request

Example Response

Error Responses

Full Lead Object