---
title: "Create Lead"
method: POST
path: "/api/leads"
tags: ["Leads"]
---

# Create Lead

`POST /api/leads`

## Request

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

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.

## Request body

- CreateLeadRequest: At least one of externalId, name, email, phone, or custom is required.
  - `externalId` string: Customer-owned lead identifier, unique within the organization. Whitespace is trimmed and the value acts as an idempotency key.
  - `name` string: Lead name
  - `email` string, email: Lead email
  - `phone` string: Lead phone number
  - `custom` union: Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses.
    - string
    - object
  - `note` string: Note to attach to the lead
  - `sessionId` string: 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.
  - `website` string: Website URL
  - `path` string: Page path
  - `gclid` string: Google Ads Click ID
  - `dclid` string: Google Display Click ID
  - `wbraid` string: Google Ads web-to-app click ID
  - `gbraid` string: Google Ads app-to-web click ID
  - `fbc` string: Meta (Facebook) Click ID
  - `fbp` string: Meta (Facebook) Browser ID
  - `ga4cid` string: Google Analytics 4 Client ID
  - `ga4sid` string: Google Analytics 4 Session ID
  - `li_fat_id` string: LinkedIn Click ID
  - `msclkid` string: Microsoft Ads Click ID
  - `ttclid` string: TikTok Click ID
  - `twclid` string: X (Twitter) Click ID
  - `rdt_cid` string: Reddit Click ID
  - `sccid` string: Snapchat Click ID
  - `epik` string: Pinterest click ID
  - `utm_source` string: UTM source
  - `utm_medium` string: UTM medium
  - `utm_campaign` string: UTM campaign
  - `ad_storage` union: Ad storage consent. Accepts booleans or strings; only `"true"` (case-insensitive) is treated as true.
    - boolean
    - string
  - `ad_user_data` union: Ad user data consent. Accepts booleans or strings; only `"true"` (case-insensitive) is treated as true.
    - boolean
    - string
  - `ad_personalization` union: Ad personalization consent. Accepts booleans or strings; only `"true"` (case-insensitive) is treated as true.
    - boolean
    - string
  - `analytics_storage` union: Analytics storage consent. Accepts booleans or strings; only `"true"` (case-insensitive) is treated as true.
    - boolean
    - string

## Response `200`

Existing lead returned for an idempotent external ID replay

- object
  - `success` boolean
  - `data` object
    - `id` string
    - `externalId` string, nullable
    - `created` boolean
    - `message` string
  - `meta` Meta
    - `requestId` string
    - `timestamp` string, date-time

## Other responses

- `201`: Lead created successfully
- `400`: Invalid JSON, missing required field, invalid field values, or invalid sessionId
- `401`: Missing or invalid API key
- `403`: Lead rejected by filtering rules
- `409`: The external ID is already assigned to a lead with conflicting email or phone data
- `500`: Server error

---

[API](https://skmtc.dev/octanist/apis/octanist-api.md) - [All operations](https://skmtc.dev/octanist/apis/octanist-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octanist/apis/octanist-api/revisions/29a41aff4975?raw)
