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": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "gclid": "abc123",
  "fbc": "fb.1.123456789",
  "fbp": "fb.1.987654321",
  "ga4cid": "ga4_client_id",
  "ga4sid": "ga4_session_id",
  "li_fat_id": "linkedin_id",
  "msclkid": "microsoft_click_id",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "winter_sale",
  "website": "https://example.com",
  "path": "/contact",
  "ad_storage": false,
  "ad_user_data": false,
  "ad_personalization": false,
  "analytics_storage": false,
  "custom": "{\"custom_field\": \"value\"}",
  "note": "Interested in enterprise plan"
}'
{
  "id": "lead_123"
}
Create a new lead in your Octanist system. At least one of name, email, phone, or custom is required.

​
Required Fields

At least one of the following must be provided:
  • name - Lead name
  • email - Lead email address
  • phone - Lead phone number
  • custom - Custom JSON string with additional data

​
Attribution Fields

Include these fields to track lead sources and enable proper attribution:
  • Google Ads: gclid (Google Click ID)
  • Facebook/Meta: fbc (Facebook Click ID), fbp (Facebook Browser ID)
  • Google Analytics: ga4cid (Client ID), ga4sid (Session ID)
  • LinkedIn: li_fat_id (First-Party Ad Tracking ID)
  • Microsoft Ads: msclkid (Microsoft Click ID)
  • UTM Parameters: utm_source, utm_medium, utm_campaign
For GDPR compliance, include consent status:
  • ad_storage - Cookie consent for ad storage
  • ad_user_data - Cookie consent for ad user data
  • ad_personalization - Cookie consent for ad personalization
  • analytics_storage - Cookie consent for analytics storage
Values can be true, false, or string values like "granted", "denied".

​
Example Usage

​
Basic lead creation

curl -X POST "https://octanist.com/api/leads" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1234567890",
    "note": "Interested in enterprise plan"
  }'

​
Lead with full attribution

curl -X POST "https://octanist.com/api/leads" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "gclid": "abc123",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "winter_sale",
    "website": "https://example.com",
    "path": "/contact"
  }'

​
Response

Returns the created lead ID: 
{
  "id": "lead_123"
}

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

​
name
string

Lead name

Example:

"Jane Smith"

​
email
string<email>

Lead email

Example:

"jane@example.com"

​
phone
string

Lead phone number

Example:

"+1234567890"

​
gclid
string

Google Click ID

Example:

"abc123"

​
fbc
string

Facebook Click ID

Example:

"fb.1.123456789"

​
fbp
string

Facebook Browser ID

Example:

"fb.1.987654321"

​
ga4cid
string

Google Analytics 4 Client ID

Example:

"ga4_client_id"

​
ga4sid
string

Google Analytics 4 Session ID

Example:

"ga4_session_id"

​
li_fat_id
string

LinkedIn First-Party Ad Tracking ID

Example:

"linkedin_id"

​
msclkid
string

Microsoft Click ID

Example:

"microsoft_click_id"

​
utm_source
string

UTM source parameter

Example:

"google"

​
utm_medium
string

UTM medium parameter

Example:

"cpc"

​
utm_campaign
string

UTM campaign parameter

Example:

"winter_sale"

​
website
string

Referrer website

Example:

"https://example.com"

​
path
string

Page path where lead was captured

Example:

"/contact"

​
ad_storage

Cookie consent: ad_storage

Example:

false

​
ad_user_data

Cookie consent: ad_user_data

Example:

false

​
ad_personalization

Cookie consent: ad_personalization

Example:

false

​
analytics_storage

Cookie consent: analytics_storage

Example:

false

​
custom
string

Custom JSON string for additional data

Example:

"{\"custom_field\": \"value\"}"

​
note
string

Notes about the lead

Example:

"Interested in enterprise plan"

Response

Lead created successfully

​
id
string
Example:

"lead_123"