Leads

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

get/api/leads

Request

  • Base URL
    https://octanist.com
  • Auth
    API key in header X-API-KEY

Query parameters

limitinteger

Results per page (1-100)

pageinteger

Page number

sortstring
Example:createdAt:desc

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

searchstring

Search across external ID, name, email, and phone

fieldsstring
Example:id,externalId,name,email,status,value

Comma-separated fields to return. The id field is always included. Use session and sessions to include pixel session objects.

statusstring
Example:won

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

externalIdstring
Example:QUOTE-2026-0042

Filter by an exact customer-owned external lead ID

source'inbound' | 'gtm' | 'api' | 'manual' | 'wordpress' | 'import'

Filter by lead source

labelIdstring

Filter by label ID

websitestring

Filter by website URL

utm_sourcestring

Filter by UTM source

utm_mediumstring

Filter by UTM medium

utm_campaignstring

Filter by UTM campaign

updated_afterstring date-time

Legacy parameter. Maps to updatedAt[gte].

Response

Paginated list of leads

successboolean

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