{
  "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.3.0",
    "contact": {
      "name": "Octanist Support",
      "url": "https://octanist.com/docs"
    }
  },
  "servers": [
    {
      "url": "https://octanist.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "paths": {
    "/api/check": {
      "post": {
        "summary": "Check API Key",
        "description": "Validate that your API key is working correctly. Useful for integration testing (e.g., Zapier connection setup).",
        "tags": ["Other"],
        "responses": {
          "200": {
            "description": "API key is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/leads": {
      "get": {
        "summary": "Get Leads",
        "description": "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.",
        "tags": ["Leads"],
        "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. Use `session` and `sessions` to include pixel session objects.",
            "schema": {
              "type": "string",
              "example": "id,externalId,name,email,status,value"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by lead status: `open`, `won`, or `lost`. Multiple values can be comma-separated. For qualified leads use `qualifiedAt[exists]=true`.",
            "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, for example `pixel`, `wordpress`, `gtm`, `api`, `manual`, `import`, or `call`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "labelId",
            "in": "query",
            "description": "Filter by label ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "website",
            "in": "query",
            "description": "Filter by website domain",
            "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"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Lead",
        "description": "Create a new lead. At least one of `externalId`, `name`, `email`, `phone`, or `custom` must be provided. An external ID is unique within the organization and acts as an idempotency key. Replays return the existing lead unless supplied email or phone data conflicts. Send `sessionId` to link the lead to an existing Octanist pixel session. When `sessionId` is provided, direct attribution fields in the same request are not merged into the existing session.",
        "tags": ["Leads"],
        "requestBody": {
          "description": "Lead data. At least one of externalId, name, email, phone, or custom is required.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLeadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing lead returned for an idempotent external ID replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "lead_abc123"
                        },
                        "externalId": {
                          "type": "string",
                          "nullable": true,
                          "example": "QUOTE-2026-0042"
                        },
                        "created": {
                          "type": "boolean",
                          "example": false
                        },
                        "message": {
                          "type": "string",
                          "example": "Existing lead returned"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Lead created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "lead_abc123"
                        },
                        "externalId": {
                          "type": "string",
                          "nullable": true,
                          "example": "QUOTE-2026-0042"
                        },
                        "created": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string",
                          "example": "Lead added"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing required field, invalid field values, or invalid sessionId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Lead rejected by lead filtering, or the organization is a read-only demo",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "The external ID is already assigned to a lead with conflicting email or phone data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update Lead",
        "description": "Update an existing lead. Matches leads by `id`, `externalId`, `email`, or `phone` (in that priority order). At least one identifier is required. `email` and `phone` can be strings or arrays of up to 10 strings. Array values are tried sequentially. The external ID is used for lookup and is not changed by this endpoint. When no lead matches, the response is 200 with `matched: false`. Status changes go forward only, and a won lead needs a value above 0.",
        "tags": ["Leads"],
        "requestBody": {
          "description": "Lead update data. At least one of id, externalId, email, or phone is required.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLeadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lead updated, or no lead matched (`matched: false`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "leadId": {
                          "type": "string",
                          "example": "lead_abc123",
                          "nullable": true
                        },
                        "externalId": {
                          "type": "string",
                          "nullable": true,
                          "example": "QUOTE-2026-0042"
                        },
                        "leadsUpdated": {
                          "type": "integer",
                          "example": 1
                        },
                        "message": {
                          "type": "string",
                          "example": "Lead updated successfully"
                        },
                        "matched": {
                          "type": "boolean",
                          "description": "Only present, and `false`, when no lead matched",
                          "example": false
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing identifier, invalid value, or a won update without a value above 0",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Several leads match and the organization returns an error for multiple matches, or the lead changed during the update",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The organization is a read-only demo",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/leads/{id}": {
      "get": {
        "summary": "Get Lead by ID",
        "description": "Retrieve a single lead by ID. Includes the converting pixel `session`, scoped journey `sessions`, and flattened attribution fields for backward compatibility.",
        "tags": ["Leads"],
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "post": {
        "summary": "Get Stats",
        "description": "Retrieve dashboard statistics including usage, lead counts, and conversion metrics. A JSON body is required, even if empty (`{}`).",
        "tags": ["Analytics"],
        "requestBody": {
          "description": "Stats request parameters",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Statistics retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/StatsData"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, missing dates for custom period, or invalid date format",
            "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/ad-spend": {
      "post": {
        "summary": "Get Ad Spend",
        "description": "Retrieve ad spend data grouped by various dimensions.",
        "tags": ["Analytics"],
        "requestBody": {
          "description": "Ad spend request parameters",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdSpendRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ad spend data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AdSpendEntry"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginatedMeta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, startDate > endDate, or invalid date format",
            "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": {
      "PixelSession": {
        "type": "object",
        "description": "Public converting pixel session. Omits organizationId, ip, userAgent, octaCid, and Google Ads enrichment internals.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Pixel session ID",
            "example": "sess_abc123"
          },
          "source": {
            "type": "string",
            "description": "Session source",
            "example": "pixel"
          },
          "visitorId": {
            "type": "string",
            "nullable": true,
            "description": "Visitor ID",
            "example": "visitor_abc"
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Session start timestamp",
            "example": "2026-01-15T10:00:00.000Z"
          },
          "lastActivityAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Last activity timestamp",
            "example": "2026-01-15T10:28:00.000Z"
          },
          "consentAnalytics": {
            "type": "boolean",
            "nullable": true,
            "description": "Analytics consent",
            "example": true
          },
          "consentMarketing": {
            "type": "boolean",
            "nullable": true,
            "description": "Marketing consent",
            "example": true
          },
          "consentSource": {
            "type": "string",
            "nullable": true,
            "description": "Consent source",
            "example": "granted"
          },
          "gclid": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Click ID",
            "example": "abc123"
          },
          "gclsrc": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads click source"
          },
          "gclidCapturedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When gclid was captured",
            "example": "2026-01-15T10:00:05.000Z"
          },
          "gclidSource": {
            "type": "string",
            "nullable": true,
            "description": "How gclid was captured",
            "example": "url"
          },
          "dclid": {
            "type": "string",
            "nullable": true,
            "description": "Google Display Click ID"
          },
          "wbraid": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads web-to-app click ID"
          },
          "gbraid": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads app-to-web click ID"
          },
          "fbc": {
            "type": "string",
            "nullable": true,
            "description": "Meta (Facebook) Click ID"
          },
          "fbp": {
            "type": "string",
            "nullable": true,
            "description": "Meta (Facebook) Browser ID"
          },
          "msclkid": {
            "type": "string",
            "nullable": true,
            "description": "Microsoft Ads Click ID"
          },
          "ttclid": {
            "type": "string",
            "nullable": true,
            "description": "TikTok Click ID"
          },
          "li_fat_id": {
            "type": "string",
            "nullable": true,
            "description": "LinkedIn Click ID"
          },
          "twclid": {
            "type": "string",
            "nullable": true,
            "description": "X (Twitter) Click ID"
          },
          "sccid": {
            "type": "string",
            "nullable": true,
            "description": "Snapchat Click ID"
          },
          "epik": {
            "type": "string",
            "nullable": true,
            "description": "Pinterest click ID"
          },
          "rdt_cid": {
            "type": "string",
            "nullable": true,
            "description": "Reddit Click ID"
          },
          "ga4cid": {
            "type": "string",
            "nullable": true,
            "description": "Google Analytics 4 Client ID"
          },
          "ga4sid": {
            "type": "string",
            "nullable": true,
            "description": "Google Analytics 4 Session ID"
          },
          "utm_source": {
            "type": "string",
            "nullable": true,
            "description": "UTM source",
            "example": "google"
          },
          "utm_medium": {
            "type": "string",
            "nullable": true,
            "description": "UTM medium",
            "example": "cpc"
          },
          "utm_campaign": {
            "type": "string",
            "nullable": true,
            "description": "UTM campaign",
            "example": "summer_sale"
          },
          "utm_content": {
            "type": "string",
            "nullable": true,
            "description": "UTM content"
          },
          "utm_term": {
            "type": "string",
            "nullable": true,
            "description": "UTM term"
          },
          "googleAdsCustomerId": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Customer ID",
            "example": "123-456-7890"
          },
          "googleAdsClickDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Google Ads click date",
            "example": "2026-01-15"
          },
          "googleAdsCampaignId": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Campaign ID"
          },
          "googleAdsCampaignName": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Campaign Name"
          },
          "googleAdsAdGroupId": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Ad Group ID"
          },
          "googleAdsAdGroupName": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Ad Group Name"
          },
          "googleAdsAdId": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads Ad ID"
          },
          "googleAdsDevice": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads device"
          },
          "googleAdsAdNetworkType": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads network type"
          },
          "googleAdsClickType": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads click type"
          },
          "googleAdsSlot": {
            "type": "string",
            "nullable": true,
            "description": "Google Ads slot"
          },
          "referrer": {
            "type": "string",
            "nullable": true,
            "description": "Referring URL",
            "example": "https://google.com"
          },
          "domain": {
            "type": "string",
            "nullable": true,
            "description": "Website domain",
            "example": "example.com"
          },
          "path": {
            "type": "string",
            "nullable": true,
            "description": "Page path",
            "example": "/pricing"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Detected country code",
            "example": "NL"
          },
          "deviceType": {
            "type": "string",
            "nullable": true,
            "description": "Device type",
            "example": "desktop"
          }
        }
      },
      "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", "won", "lost"],
            "description": "Lead status. Qualified leads keep status `open` and have a `qualifiedAt` date.",
            "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",
            "description": "How the lead entered Octanist, for example `pixel`, `wordpress`, `gtm`, `api`, `manual`, `import`, `call`, `meta`, `tiktok`, `snapchat`, or `inbound` for older leads.",
            "example": "pixel"
          },
          "website": {
            "type": "string",
            "description": "Website domain from the lead's converting session",
            "example": "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"
          },
          "session": {
            "nullable": true,
            "description": "Public converting pixel session, or null when the lead has no linked pixel session. Omits organizationId, ip, userAgent, and octaCid.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PixelSession"
              }
            ]
          },
          "sessions": {
            "type": "array",
            "description": "Scoped journey sessions for this lead. Same shape as session.",
            "items": {
              "$ref": "#/components/schemas/PixelSession"
            }
          }
        }
      },
      "CreateLeadRequest": {
        "type": "object",
        "description": "At least one of externalId, name, email, phone, or custom is required.",
        "properties": {
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Customer-owned lead identifier, unique within the organization. Whitespace is trimmed and the value acts as an idempotency key.",
            "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"
          },
          "custom": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              },
              {
                "type": "array"
              }
            ],
            "description": "Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses."
          },
          "note": {
            "type": "string",
            "description": "Note to attach to the lead"
          },
          "sessionId": {
            "type": "string",
            "description": "Existing Octanist pixel session ID. Use the value from the hidden `octa_sid` form field or `window.OCT.getSessionId()`. When provided, the lead uses the existing session attribution and direct attribution fields in this request are ignored.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "website": {
            "type": "string",
            "description": "Website URL",
            "example": "https://example.com"
          },
          "path": {
            "type": "string",
            "description": "Page path",
            "example": "/contact"
          },
          "gclid": {
            "type": "string",
            "description": "Google Ads Click ID"
          },
          "dclid": {
            "type": "string",
            "description": "Google Display Click ID"
          },
          "wbraid": {
            "type": "string",
            "description": "Google Ads web-to-app click ID"
          },
          "gbraid": {
            "type": "string",
            "description": "Google Ads app-to-web click ID"
          },
          "fbc": {
            "type": "string",
            "description": "Meta (Facebook) Click ID"
          },
          "fbp": {
            "type": "string",
            "description": "Meta (Facebook) Browser ID"
          },
          "ga4cid": {
            "type": "string",
            "description": "Google Analytics 4 Client ID"
          },
          "ga4sid": {
            "type": "string",
            "description": "Google Analytics 4 Session ID"
          },
          "li_fat_id": {
            "type": "string",
            "description": "LinkedIn Click ID"
          },
          "msclkid": {
            "type": "string",
            "description": "Microsoft Ads Click ID"
          },
          "ttclid": {
            "type": "string",
            "description": "TikTok Click ID"
          },
          "twclid": {
            "type": "string",
            "description": "X (Twitter) Click ID"
          },
          "rdt_cid": {
            "type": "string",
            "description": "Reddit Click ID"
          },
          "sccid": {
            "type": "string",
            "description": "Snapchat Click ID"
          },
          "epik": {
            "type": "string",
            "description": "Pinterest click ID"
          },
          "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"
          },
          "ad_storage": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": ["true", "false"]
              }
            ],
            "default": false,
            "description": "Ad storage consent. Boolean, or the string \"true\" or \"false\" (case-insensitive). Other strings return 400."
          },
          "ad_user_data": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": ["true", "false"]
              }
            ],
            "default": false,
            "description": "Ad user data consent. Boolean, or the string \"true\" or \"false\" (case-insensitive). Other strings return 400."
          },
          "ad_personalization": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": ["true", "false"]
              }
            ],
            "default": false,
            "description": "Ad personalization consent. Boolean, or the string \"true\" or \"false\" (case-insensitive). Other strings return 400."
          },
          "analytics_storage": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string",
                "enum": ["true", "false"]
              }
            ],
            "default": false,
            "description": "Analytics storage consent. Boolean, or the string \"true\" or \"false\" (case-insensitive). Other strings return 400."
          }
        }
      },
      "UpdateLeadRequest": {
        "type": "object",
        "description": "At least one of id, externalId, email, or phone is required as an identifier. `email` and `phone` can be strings or arrays of up to 10 strings. Identifiers are tried sequentially: id first, then externalId, then email values in order, then phone values in order. externalId is used for lookup and is not changed by this endpoint.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Lead ID (highest priority match)",
            "example": "lead_abc123"
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Customer-owned lead identifier (second priority match). Whitespace is trimmed.",
            "example": "QUOTE-2026-0042"
          },
          "email": {
            "oneOf": [
              {
                "type": "string",
                "format": "email"
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "email"
                },
                "minItems": 1,
                "maxItems": 10
              }
            ],
            "description": "Lead email or ordered email candidates (third priority match). Arrays are tried sequentially.",
            "example": "john@example.com"
          },
          "phone": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "maxItems": 10
              }
            ],
            "description": "Lead phone or ordered phone candidates (fourth priority match). Arrays are tried sequentially after all email candidates.",
            "example": "+1234567890"
          },
          "status": {
            "type": "string",
            "enum": ["qualified", "won", "lost"],
            "description": "New status. Takes precedence over `changedTo` if both are provided.",
            "example": "won"
          },
          "changedTo": {
            "type": "string",
            "enum": ["qualified", "won", "lost"],
            "description": "Legacy alias for `status` (same values).",
            "example": "won"
          },
          "value": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Lead value. Strings such as \"1.234,56\" or \"1,234.56\" are converted to numbers. A string that is not a number returns 400.",
            "example": 5000
          },
          "note": {
            "type": "string",
            "description": "Note to attach to the lead"
          },
          "lossReason": {
            "type": "string",
            "description": "Reason for loss (only used when status is `lost`)"
          }
        }
      },
      "StatsRequest": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "enum": ["current", "previous", "custom"],
            "default": "current",
            "description": "Period to retrieve statistics for"
          },
          "startDate": {
            "type": "string",
            "format": "date",
            "description": "Start date (YYYY-MM-DD). Required when period is `custom`.",
            "example": "2026-01-01"
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "End date (YYYY-MM-DD). Required when period is `custom`.",
            "example": "2026-03-01"
          }
        }
      },
      "StatsData": {
        "type": "object",
        "properties": {
          "usage": {
            "type": "object",
            "properties": {
              "leadsUsed": {
                "type": "integer",
                "example": 150
              },
              "leadsLimit": {
                "type": "integer",
                "example": 500
              },
              "lockedLeads": {
                "type": "integer",
                "example": 0
              },
              "periodStart": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Null if no active subscription",
                "example": "2026-01-01T00:00:00.000Z"
              },
              "periodEnd": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Null if no active subscription",
                "example": "2026-03-01T23:59:59.999Z"
              }
            }
          },
          "leads": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "example": 150
              },
              "byStatus": {
                "type": "object",
                "properties": {
                  "open": {
                    "type": "integer",
                    "example": 75
                  },
                  "won": {
                    "type": "integer",
                    "example": 50
                  },
                  "lost": {
                    "type": "integer",
                    "example": 25
                  }
                },
                "description": "Lead counts per status. Qualified leads have status open."
              },
              "bySource": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "example": {
                  "pixel": 120,
                  "api": 20,
                  "manual": 10
                }
              }
            }
          },
          "conversion": {
            "type": "object",
            "properties": {
              "qualified": {
                "type": "integer",
                "example": 80
              },
              "qualificationRate": {
                "type": "number",
                "example": 0.7
              },
              "winRate": {
                "type": "number",
                "example": 0.625
              },
              "averageValue": {
                "type": "number",
                "example": 2500
              },
              "totalValue": {
                "type": "number",
                "example": 125000
              }
            }
          }
        }
      },
      "AdSpendRequest": {
        "type": "object",
        "required": ["startDate", "endDate"],
        "properties": {
          "startDate": {
            "type": "string",
            "format": "date",
            "description": "Start date (YYYY-MM-DD)",
            "example": "2026-01-01"
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "End date (YYYY-MM-DD)",
            "example": "2026-03-01"
          },
          "platform": {
            "type": "string",
            "enum": [
              "googleads",
              "meta",
              "microsoftads",
              "linkedin",
              "snapchat",
              "tiktok"
            ],
            "description": "Filter by platform"
          },
          "groupBy": {
            "type": "string",
            "enum": ["date", "campaign", "adgroup", "platform"],
            "default": "date",
            "description": "Dimension to group results by"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 100,
            "description": "Results per page (1-500)"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Page number"
          }
        }
      },
      "AdSpendEntry": {
        "type": "object",
        "description": "Ad spend data entry. Fields vary based on the `groupBy` parameter.",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date (when groupBy is `date`)",
            "example": "2026-02-15"
          },
          "campaignId": {
            "type": "string",
            "description": "Campaign ID (when groupBy is `campaign` or `adgroup`)",
            "example": "123456789"
          },
          "campaignName": {
            "type": "string",
            "description": "Campaign name (when groupBy is `campaign` or `adgroup`)",
            "example": "Spring Sale 2026"
          },
          "adGroupId": {
            "type": "string",
            "description": "Ad group ID (when groupBy is `adgroup`)",
            "example": "987654321"
          },
          "adGroupName": {
            "type": "string",
            "description": "Ad group name (when groupBy is `adgroup`)",
            "example": "Brand Keywords"
          },
          "platform": {
            "type": "string",
            "enum": ["googleads", "meta", "microsoftads"],
            "description": "Platform (when groupBy is `campaign`, `adgroup`, or `platform`)",
            "example": "googleads"
          },
          "cost": {
            "type": "number",
            "description": "Total cost",
            "example": 1500.5
          },
          "clicks": {
            "type": "integer",
            "description": "Total clicks",
            "example": 2500
          },
          "impressions": {
            "type": "integer",
            "description": "Total impressions",
            "example": 50000
          },
          "conversions": {
            "type": "integer",
            "description": "Total conversions",
            "example": 125
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "example": "req_a1b2c3d4e5f6"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-03-10T12:00: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"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "API key for authentication"
      }
    }
  }
}
