> ## 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 Lead by ID

> Retrieve a single lead by ID

## Path Parameters

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Lead ID     |

## Example Request

```bash theme={null}
curl -X GET \
  -H "X-API-KEY: your_api_key" \
  "https://octanist.com/api/leads/lead_abc123"
```

## Example Response

Returns the full lead object (see [Full Lead Object](/docs/api-reference/endpoint/get-leads#full-lead-object)).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "status": "won",
    "value": 5000,
    "source": "gtm",
    "website": "https://example.com",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-02-20T14:00:00.000Z"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}
```

## Error Responses

| Status | Code             | Description                |
| ------ | ---------------- | -------------------------- |
| 401    | `UNAUTHORIZED`   | Missing or invalid API key |
| 404    | `NOT_FOUND`      | Lead not found             |
| 500    | `INTERNAL_ERROR` | Server error               |


## OpenAPI

````yaml GET /api/leads/{id}
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/{id}:
    get:
      tags:
        - Leads
      summary: Get Lead by ID
      description: Retrieve a single lead by ID.
      parameters:
        - name: id
          in: path
          required: true
          description: Lead ID
          schema:
            type: string
            example: lead_abc123
      responses:
        '200':
          description: Lead found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Lead'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Lead not found
          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'
    Meta:
      type: object
      properties:
        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'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````