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

# Create Lead

`POST /api/leads`

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.net/octanist/apis/octanist-api.md) · [All operations](https://skmtc.net/octanist/apis/octanist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octanist/octanist-api/revisions/a0620637a051/schema)