Skip to main content
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>",
  "website": "https://example.com",
  "path": "/contact",
  "gclid": "<string>",
  "fbc": "<string>",
  "fbp": "<string>",
  "ga4cid": "<string>",
  "ga4sid": "<string>",
  "li_fat_id": "<string>",
  "msclkid": "<string>",
  "ttclid": "<string>",
  "twclid": "<string>",
  "rdt_cid": "<string>",
  "sccid": "<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.

​
Request Body

FieldTypeRequiredDefaultDescription
namestringNo*-Lead name
emailstringNo*-Lead email
phonestringNo*-Lead phone number
customstring | objectNo*-Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses.
notestringNo-Note to attach to the lead
websitestringNo-Website URL
pathstringNo-Page path
gclidstringNo-Google Ads Click ID
fbcstringNo-Meta (Facebook) Click ID
fbpstringNo-Meta (Facebook) Browser ID
ga4cidstringNo-Google Analytics 4 Client ID
ga4sidstringNo-Google Analytics 4 Session ID
li_fat_idstringNo-LinkedIn Click ID
msclkidstringNo-Microsoft Ads Click ID
ttclidstringNo-TikTok Click ID
twclidstringNo-X (Twitter) Click ID
rdt_cidstringNo-Reddit Click ID
sccidstringNo-Snapchat Click ID
utm_sourcestringNo-UTM source
utm_mediumstringNo-UTM medium
utm_campaignstringNo-UTM campaign
ad_storageboolean | stringNofalseAd storage consent
ad_user_databoolean | stringNofalseAd user data consent
ad_personalizationboolean | stringNofalseAd personalization consent
analytics_storageboolean | stringNofalseAnalytics 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.

​
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",
    "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

StatusCodeDescription
400VALIDATION_ERRORInvalid JSON, missing required field, or invalid field values
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENLead rejected by filtering rules
500INTERNAL_ERRORServer 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"

​
email
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

​
website
string

Website URL

Example:

"https://example.com"

​
path
string

Page path

Example:

"/contact"

​
gclid
string

Google Ads 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

​
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
​
meta
object