Create Lead

curl --request POST \
  --url https://octanist.com/api/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "custom": "<string>",
  "note": "<string>",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "website": "https://example.com",
  "path": "/contact",
  "gclid": "<string>",
  "dclid": "<string>",
  "wbraid": "<string>",
  "gbraid": "<string>",
  "fbc": "<string>",
  "fbp": "<string>",
  "ga4cid": "<string>",
  "ga4sid": "<string>",
  "li_fat_id": "<string>",
  "msclkid": "<string>",
  "ttclid": "<string>",
  "twclid": "<string>",
  "rdt_cid": "<string>",
  "sccid": "<string>",
  "epik": "<string>",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "<string>",
  "ad_storage": false,
  "ad_user_data": false,
  "ad_personalization": false,
  "analytics_storage": false
}
'

{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "message": "Lead added"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

POST

api

leads

Create Lead

curl --request POST \
  --url https://octanist.com/api/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "custom": "<string>",
  "note": "<string>",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "website": "https://example.com",
  "path": "/contact",
  "gclid": "<string>",
  "dclid": "<string>",
  "wbraid": "<string>",
  "gbraid": "<string>",
  "fbc": "<string>",
  "fbp": "<string>",
  "ga4cid": "<string>",
  "ga4sid": "<string>",
  "li_fat_id": "<string>",
  "msclkid": "<string>",
  "ttclid": "<string>",
  "twclid": "<string>",
  "rdt_cid": "<string>",
  "sccid": "<string>",
  "epik": "<string>",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "<string>",
  "ad_storage": false,
  "ad_user_data": false,
  "ad_personalization": false,
  "analytics_storage": false
}
'

{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "message": "Lead added"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

At least one of name, email, phone, or custom must be provided. When you include attribution fields such as click IDs, UTM parameters, website, path, or consent fields, Octanist stores that attribution on the lead’s session. Existing API integrations can keep sending those fields directly. If the Octanist pixel is installed on the website, you can also send sessionId to link the lead to an existing pixel session. This is the preferred setup for server-side form capture because it keeps the lead connected to the original page views and attribution. When sessionId is provided, Octanist links the lead to that existing session and uses the attribution already stored on the session. Direct attribution fields in the same request are only used when sessionId is missing.

Request Body

Field	Type	Required	Default	Description
`name`	string	No*	-	Lead name
`email`	string	No*	-	Lead email
`phone`	string	No*	-	Lead phone number
`custom`	string \| object	No*	-	Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses.
`note`	string	No	-	Note to attach to the lead
`sessionId`	string	No	-	Existing Octanist pixel session ID. Send the value from the hidden `octa_sid` form field or `window.OCT.getSessionId()`.
`website`	string	No	-	Website URL
`path`	string	No	-	Page path
`gclid`	string	No	-	Google Ads Click ID
`dclid`	string	No	-	Google Display Click ID
`wbraid`	string	No	-	Google Ads web-to-app click ID
`gbraid`	string	No	-	Google Ads app-to-web click ID
`fbc`	string	No	-	Meta (Facebook) Click ID
`fbp`	string	No	-	Meta (Facebook) Browser ID
`ga4cid`	string	No	-	Google Analytics 4 Client ID
`ga4sid`	string	No	-	Google Analytics 4 Session ID
`li_fat_id`	string	No	-	LinkedIn Click ID
`msclkid`	string	No	-	Microsoft Ads Click ID
`ttclid`	string	No	-	TikTok Click ID
`twclid`	string	No	-	X (Twitter) Click ID
`rdt_cid`	string	No	-	Reddit Click ID
`sccid`	string	No	-	Snapchat Click ID
`epik`	string	No	-	Pinterest click ID
`utm_source`	string	No	-	UTM source
`utm_medium`	string	No	-	UTM medium
`utm_campaign`	string	No	-	UTM campaign
`ad_storage`	boolean \| string	No	`false`	Ad storage consent
`ad_user_data`	boolean \| string	No	`false`	Ad user data consent
`ad_personalization`	boolean \| string	No	`false`	Ad personalization consent
`analytics_storage`	boolean \| string	No	`false`	Analytics storage consent

* At least one of name, email, phone, or custom is required. Consent fields accept both booleans and strings. Only the string "true" (case-insensitive) is treated as true; any other string value is treated as false.

Session linking

When the pixel runs on a page, it creates a session ID and stores it in sessionStorage as octa_sid. The pixel also injects a hidden field into forms:

<input type="hidden" name="octa_sid" value="..." />

For Elementor forms, the pixel also injects:

<input type="hidden" name="form_fields[octa_sid]" value="..." />

Your server should read that value from the submitted form and send it to the API as sessionId.

{
  "name": "John Doe",
  "email": "john@example.com",
  "sessionId": "value-from-octa_sid"
}

If sessionId is valid, Octanist links the new lead to the existing pixel session. If sessionId is missing, Octanist creates a synthetic session from the attribution fields in the request. Direct attribution fields in the request are not merged into an existing pixel session when sessionId is provided.

Never expose your API key in browser JavaScript. Submit the form to your own backend first, then call the Octanist API from your server.

Example Request

curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "gclid": "abc123",
    "utm_source": "google",
    "utm_medium": "cpc",
    "ad_storage": true,
    "ad_user_data": true
  }' \
  "https://octanist.com/api/leads"

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "message": "Lead added"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid JSON, missing required field, invalid field values, or invalid `sessionId`
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Lead rejected by filtering rules
500	`INTERNAL_ERROR`	Server error

Authorizations

X-API-KEY

string

header

required

API key for authentication

Body

application/json

Lead data. At least one of name, email, phone, or custom is required.

At least one of name, email, phone, or custom is required.

name

string

Lead name

Example:

"John Doe"

string<email>

Lead email

Example:

"john@example.com"

phone

string

Lead phone number

Example:

"+1234567890"

custom

Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses.

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.

Example:

"550e8400-e29b-41d4-a716-446655440000"

website

string

Website URL

Example:

"https://example.com"

path

string

Page path

Example:

"/contact"

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

Example:

"google"

utm_medium

string

UTM medium

Example:

"cpc"

utm_campaign

string

UTM campaign

ad_storage

default:false

Ad storage consent. Accepts booleans or strings; only "true" (case-insensitive) is treated as true.

ad_user_data

default:false

Ad user data consent. Accepts booleans or strings; only "true" (case-insensitive) is treated as true.

ad_personalization

default:false

Ad personalization consent. Accepts booleans or strings; only "true" (case-insensitive) is treated as true.

analytics_storage

default:false

Analytics storage consent. Accepts booleans or strings; only "true" (case-insensitive) is treated as true.

Response

Lead created successfully

success

boolean

Example:

true

data

object

Show child attributes

​Request Body

​Session linking

​Example Request

​Example Response (201 Created)

​Error Responses

Authorizations

Body

Response

Request Body

Session linking

Example Request

Example Response (201 Created)

Error Responses