Sign in

v1

latestOpenAPI 3.0.12026-08-0671048.4 KB
Leads

Create Lead

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.

post/api/leads

Request body

externalIdstring

Customer-owned lead identifier, unique within the organization. Whitespace is trimmed and the value acts as an idempotency key.

namestring

Lead name

emailstring email

Lead email

phonestring

Lead phone number

notestring

Note to attach to the lead

sessionIdstring

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.

websitestring

Website URL

pathstring

Page path

gclidstring

Google Ads Click ID

dclidstring

Google Display Click ID

wbraidstring

Google Ads web-to-app click ID

gbraidstring

Google Ads app-to-web click ID

fbcstring

Meta (Facebook) Click ID

fbpstring

Meta (Facebook) Browser ID

ga4cidstring

Google Analytics 4 Client ID

ga4sidstring

Google Analytics 4 Session ID

li_fat_idstring

LinkedIn Click ID

msclkidstring

Microsoft Ads Click ID

ttclidstring

TikTok Click ID

twclidstring

X (Twitter) Click ID

rdt_cidstring

Reddit Click ID

sccidstring

Snapchat Click ID

epikstring

Pinterest click ID

utm_sourcestring

UTM source

utm_mediumstring

UTM medium

utm_campaignstring

UTM campaign

Example request

{
  "externalId": "QUOTE-2026-0042",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "website": "https://example.com",
  "path": "/contact",
  "utm_source": "google",
  "utm_medium": "cpc"
}

Response

Existing lead returned for an idempotent external ID replay

successboolean

Example response

{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "message": "Existing lead returned"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}