Get Leads
Changed onRetrieve a paginated list of leads with optional filtering, sorting, and field selection. Each lead includes the converting pixel session, scoped journey sessions, and flattened attribution fields for backward compatibility.
Request
- Base URLhttps://octanist.com
- AuthAPI key in header X-API-KEY
Query parameters
Results per page (1-100)
Page number
Sort field and direction (e.g. createdAt:desc, value:asc). Multiple fields can be combined with commas.
Search across external ID, name, email, and phone
Comma-separated fields to return. The id field is always included. Use session and sessions to include pixel session objects.
Filter by lead status. Multiple values can be comma-separated.
Filter by an exact customer-owned external lead ID
Filter by lead source
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].
Response
Paginated list of leads
Example response
{
"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\"}",
"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",
"session": {
"id": "sess_abc123",
"source": "pixel",
"visitorId": "visitor_abc",
"startedAt": "2026-01-15T10:00:00.000Z",
"lastActivityAt": "2026-01-15T10:28:00.000Z",
"consentAnalytics": true,
"consentMarketing": true,
"consentSource": "granted",
"gclid": "abc123",
"gclidCapturedAt": "2026-01-15T10:00:05.000Z",
"gclidSource": "url",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"googleAdsCustomerId": "123-456-7890",
"googleAdsClickDate": "2026-01-15",
"referrer": "https://google.com",
"domain": "example.com",
"path": "/pricing",
"country": "NL",
"deviceType": "desktop"
},
"sessions": [
{
"id": "sess_abc123",
"source": "pixel",
"visitorId": "visitor_abc",
"startedAt": "2026-01-15T10:00:00.000Z",
"lastActivityAt": "2026-01-15T10:28:00.000Z",
"consentAnalytics": true,
"consentMarketing": true,
"consentSource": "granted",
"gclid": "abc123",
"gclidCapturedAt": "2026-01-15T10:00:05.000Z",
"gclidSource": "url",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"googleAdsCustomerId": "123-456-7890",
"googleAdsClickDate": "2026-01-15",
"referrer": "https://google.com",
"domain": "example.com",
"path": "/pricing",
"country": "NL",
"deviceType": "desktop"
}
]
}
],
"meta": {
"pagination": {
"limit": 50,
"page": 1,
"totalPages": 5,
"total": 234,
"hasMore": true
},
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}Changes
- info
added the optional property
//to the response with the status - info
added the optional property
//to the response with the status
- info