> ## Documentation Index
> Fetch the complete documentation index at: https://octanist.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Leads

> Retrieve a paginated list of leads with optional filtering, sorting, and field selection

## 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
```

**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                                                           |
| ------------- | --------------------------------------------------------------------- |
| `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 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`, `externalId`, `name`, `email`, `status`

## Field Selection

Request only specific fields to reduce response size:

```
?fields=id,externalId,name,email,status,value
```

The `id` field is always included. Supported field names are the fields shown in [Full Lead Object](#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

```bash theme={null}
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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
}
```


## OpenAPI

````yaml GET /api/leads
openapi: 3.0.1
info:
  title: Octanist API
  description: >-
    The Octanist API allows you to manage leads, retrieve statistics, and access
    ad spend data.
  version: 2.2.0
  contact:
    name: Octanist Support
    url: https://octanist.com/docs
servers:
  - url: https://octanist.com
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /api/leads:
    get:
      tags:
        - Leads
      summary: Get Leads
      description: >-
        Retrieve a paginated list of leads with optional filtering, sorting, and
        field selection.
      parameters:
        - name: limit
          in: query
          description: Results per page (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: sort
          in: query
          description: >-
            Sort field and direction (e.g. `createdAt:desc`, `value:asc`).
            Multiple fields can be combined with commas.
          schema:
            type: string
            default: createdAt:desc
            example: createdAt:desc
        - name: search
          in: query
          description: Search across external ID, name, email, and phone
          schema:
            type: string
        - name: fields
          in: query
          description: Comma-separated fields to return. The `id` field is always included.
          schema:
            type: string
            example: id,externalId,name,email,status,value
        - name: status
          in: query
          description: Filter by lead status. Multiple values can be comma-separated.
          schema:
            type: string
            example: won
        - name: externalId
          in: query
          description: Filter by an exact customer-owned external lead ID
          schema:
            type: string
            maxLength: 255
            example: QUOTE-2026-0042
        - name: source
          in: query
          description: Filter by lead source
          schema:
            type: string
            enum:
              - inbound
              - gtm
              - api
              - manual
              - wordpress
              - import
        - name: labelId
          in: query
          description: Filter by label ID
          schema:
            type: string
        - name: website
          in: query
          description: Filter by website URL
          schema:
            type: string
        - name: utm_source
          in: query
          description: Filter by UTM source
          schema:
            type: string
        - name: utm_medium
          in: query
          description: Filter by UTM medium
          schema:
            type: string
        - name: utm_campaign
          in: query
          description: Filter by UTM campaign
          schema:
            type: string
        - name: updated_after
          in: query
          description: Legacy parameter. Maps to `updatedAt[gte]`.
          deprecated: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Paginated list of leads
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  meta:
                    $ref: '#/components/schemas/PaginatedMeta'
        '400':
          description: Invalid filter or date parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Lead:
      type: object
      properties:
        id:
          type: string
          description: Unique lead identifier
          example: lead_abc123
        externalId:
          type: string
          nullable: true
          maxLength: 255
          description: Customer-owned lead identifier, unique within the organization
          example: QUOTE-2026-0042
        name:
          type: string
          description: Lead name
          example: John Doe
        email:
          type: string
          format: email
          description: Lead email
          example: john@example.com
        phone:
          type: string
          description: Lead phone number
          example: '+1234567890'
        status:
          type: string
          enum:
            - open
            - qualified
            - won
            - lost
          description: Lead status
          example: won
        value:
          type: number
          description: Lead value
          example: 5000
        note:
          type: string
          description: Notes about the lead
          example: Customer notes
        custom:
          type: string
          description: >-
            Custom data. Accepts a string or JSON object/array. Non-string
            values are automatically stringified. Always returned as a string in
            responses.
          example: '{"company":"Acme Inc"}'
        lossReason:
          type: string
          nullable: true
          description: Reason for loss
          example: null
        conversionName:
          type: string
          description: Conversion source name
          example: Purchase
        source:
          type: string
          enum:
            - inbound
            - gtm
            - api
            - manual
            - wordpress
            - import
          description: Lead source
          example: gtm
        website:
          type: string
          description: Website URL
          example: https://example.com
        path:
          type: string
          description: Page path where lead was captured
          example: /pricing
        referrer:
          type: string
          nullable: true
          description: Referring URL
          example: https://google.com
        country:
          type: string
          nullable: true
          description: Detected country code
          example: NL
        gclid:
          type: string
          description: Google Ads Click ID
          example: abc123
        dclid:
          type: string
          description: Google Display Click ID
          example: dclid123
        wbraid:
          type: string
          description: Google Ads web-to-app click ID
          example: wbraid123
        gbraid:
          type: string
          description: Google Ads app-to-web click ID
          example: gbraid123
        ga4cid:
          type: string
          description: Google Analytics 4 Client ID
          example: GA1.1.123456789.1234567890
        ga4sid:
          type: string
          description: Google Analytics 4 Session ID
          example: '1234567890'
        fbc:
          type: string
          description: Meta (Facebook) Click ID
          example: fb.1.1234567890.abc123
        fbp:
          type: string
          description: Meta (Facebook) Browser ID
          example: fb.1.1234567890.987654321
        msclkid:
          type: string
          description: Microsoft Ads Click ID
          example: msclkid123
        ttclid:
          type: string
          description: TikTok Click ID
          example: ttclid123
        twclid:
          type: string
          description: X (Twitter) Click ID
          example: twclid123
        rdt_cid:
          type: string
          description: Reddit Click ID
          example: rdtcid123
        sccid:
          type: string
          description: Snapchat Click ID
          example: sccid123
        epik:
          type: string
          description: Pinterest click ID
          example: epik123
        li_fat_id:
          type: string
          description: LinkedIn Click ID
          example: lifatid123
        utm_source:
          type: string
          description: UTM source
          example: google
        utm_medium:
          type: string
          description: UTM medium
          example: cpc
        utm_campaign:
          type: string
          description: UTM campaign
          example: summer_sale
        utm_content:
          type: string
          description: UTM content
          example: headline_a
        utm_term:
          type: string
          description: UTM term
          example: brand keyword
        ad_storage:
          type: boolean
          description: Ad storage consent
          example: true
        ad_user_data:
          type: boolean
          description: Ad user data consent
          example: true
        analytics_storage:
          type: boolean
          description: Analytics storage consent
          example: true
        ad_personalization:
          type: boolean
          description: Ad personalization consent
          example: true
        googleAdsCampaignId:
          type: string
          description: Google Ads Campaign ID
          example: '123456789'
        googleAdsCustomerId:
          type: string
          description: Google Ads Customer ID
          example: 123-456-7890
        googleAdsClickDate:
          type: string
          format: date
          description: Google Ads click date
          example: '2026-01-15'
        googleAdsCampaignName:
          type: string
          description: Google Ads Campaign Name
          example: Spring Sale 2026
        googleAdsAdGroupId:
          type: string
          description: Google Ads Ad Group ID
          example: '987654321'
        googleAdsAdGroupName:
          type: string
          description: Google Ads Ad Group Name
          example: Brand Keywords
        googleAdsAdId:
          type: string
          description: Google Ads Ad ID
          example: '111222333'
        googleAdsDevice:
          type: string
          description: Google Ads device
          example: DESKTOP
        googleAdsAdNetworkType:
          type: string
          description: Google Ads network type
          example: SEARCH
        googleAdsClickType:
          type: string
          description: Google Ads click type
          example: Headline
        googleAdsSlot:
          type: string
          description: Google Ads slot
          example: Search Top
        labelId:
          type: string
          description: Label ID
          example: label_xyz
        selectedConversionEventId:
          type: string
          description: Selected conversion event ID
          example: conv_123
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2026-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2026-02-20T14:00:00.000Z'
        qualifiedAt:
          type: string
          format: date-time
          nullable: true
          description: Qualification timestamp
          example: '2026-01-18T09:00:00.000Z'
        expiresAt:
          type: string
          format: date-time
          description: Expiration timestamp
          example: '2026-04-15T10:30:00.000Z'
    PaginatedMeta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            limit:
              type: integer
              example: 50
            page:
              type: integer
              example: 1
            totalPages:
              type: integer
              example: 5
            total:
              type: integer
              example: 234
            hasMore:
              type: boolean
              example: true
        requestId:
          type: string
          example: req_a1b2c3d4e5f6
        timestamp:
          type: string
          format: date-time
          example: '2026-03-10T12:00:00.000Z'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human readable error message
              example: Human readable error message
            details:
              type: object
              description: Optional additional error details
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6
        timestamp:
          type: string
          format: date-time
          example: '2026-03-10T12:00:00.000Z'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````