> ## Documentation Index
> Fetch the complete documentation index at: https://octanist.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Lead
> Create a new lead
At least one of `externalId`, `name`, `email`, `phone`, or `custom` must be provided.
Use `externalId` for a customer-owned business identifier, such as an order number, quotation number, application ID, opportunity ID, or CRM lead ID. The value is trimmed, can contain up to 255 characters, and must be unique within your Octanist organization.
When `externalId` is provided, it also acts as an idempotency key. Repeating a request with the same external ID returns the existing lead with `200 OK` and `created: false`. If the repeated request supplies an email or phone number that conflicts with the existing lead, Octanist returns `409 CONFLICT` instead.
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 |
| -------------------- | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalId` | string | No\* | - | Customer-owned lead identifier, unique within the organization (max 255 characters) |
| `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 `externalId`, `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:
```html theme={null}
```
For Elementor forms, the pixel also injects:
```html theme={null}
```
Your server should read that value from the submitted form and send it to the API as `sessionId`.
```json theme={null}
{
"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
```bash theme={null}
curl -X POST \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"externalId": "QUOTE-2026-0042",
"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)
```json theme={null}
{
"success": true,
"data": {
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"created": true,
"message": "Lead added"
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}
```
## Example Response (200 Existing Lead)
An idempotent replay with the same `externalId` returns the existing lead:
```json theme={null}
{
"success": true,
"data": {
"id": "lead_abc123",
"externalId": "QUOTE-2026-0042",
"created": false,
"message": "Existing lead returned"
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}
```
External IDs are supported by the authenticated Leads API and by pixel form mapping. The GTM DataLayer endpoint and the legacy WordPress endpoint return Octanist's internal lead UUID, but reject `externalId` input.
## 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 |
| 409 | `CONFLICT` | The external ID already belongs to a lead with conflicting email or phone data |
| 500 | `INTERNAL_ERROR` | Server error |
## OpenAPI
````yaml POST /api/leads
openapi: 3.0.1
info:
title: Octanist API
description: >-
The Octanist API allows you to manage leads, retrieve statistics, and access
ad spend data.
version: 2.2.0
contact:
name: Octanist Support
url: https://octanist.com/docs
servers:
- url: https://octanist.com
description: Production server
security:
- apiKeyAuth: []
paths:
/api/leads:
post:
tags:
- Leads
summary: Create Lead
description: >-
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.
requestBody:
description: >-
Lead data. At least one of externalId, name, email, phone, or custom
is required.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLeadRequest'
responses:
'200':
description: Existing lead returned for an idempotent external ID replay
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: string
example: lead_abc123
externalId:
type: string
nullable: true
example: QUOTE-2026-0042
created:
type: boolean
example: false
message:
type: string
example: Existing lead returned
meta:
$ref: '#/components/schemas/Meta'
'201':
description: Lead created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: string
example: lead_abc123
externalId:
type: string
nullable: true
example: QUOTE-2026-0042
created:
type: boolean
example: true
message:
type: string
example: Lead added
meta:
$ref: '#/components/schemas/Meta'
'400':
description: >-
Invalid JSON, missing required field, invalid field values, or
invalid sessionId
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Lead rejected by filtering rules
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: >-
The external ID is already assigned to a lead with conflicting email
or phone data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CreateLeadRequest:
type: object
description: At least one of externalId, name, email, phone, or custom is required.
properties:
externalId:
type: string
minLength: 1
maxLength: 255
description: >-
Customer-owned lead identifier, unique within the organization.
Whitespace is trimmed and the value acts as an idempotency key.
example: QUOTE-2026-0042
name:
type: string
description: Lead name
example: John Doe
email:
type: string
format: email
description: Lead email
example: john@example.com
phone:
type: string
description: Lead phone number
example: '+1234567890'
custom:
oneOf:
- type: string
- type: object
- type: array
description: >-
Custom data. Accepts a string or JSON object/array. Non-string
values are automatically stringified. Always returned as a string in
responses.
note:
type: string
description: Note to attach to the lead
sessionId:
type: string
description: >-
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:
type: string
description: Website URL
example: https://example.com
path:
type: string
description: Page path
example: /contact
gclid:
type: string
description: Google Ads Click ID
dclid:
type: string
description: Google Display Click ID
wbraid:
type: string
description: Google Ads web-to-app click ID
gbraid:
type: string
description: Google Ads app-to-web click ID
fbc:
type: string
description: Meta (Facebook) Click ID
fbp:
type: string
description: Meta (Facebook) Browser ID
ga4cid:
type: string
description: Google Analytics 4 Client ID
ga4sid:
type: string
description: Google Analytics 4 Session ID
li_fat_id:
type: string
description: LinkedIn Click ID
msclkid:
type: string
description: Microsoft Ads Click ID
ttclid:
type: string
description: TikTok Click ID
twclid:
type: string
description: X (Twitter) Click ID
rdt_cid:
type: string
description: Reddit Click ID
sccid:
type: string
description: Snapchat Click ID
epik:
type: string
description: Pinterest click ID
utm_source:
type: string
description: UTM source
example: google
utm_medium:
type: string
description: UTM medium
example: cpc
utm_campaign:
type: string
description: UTM campaign
ad_storage:
oneOf:
- type: boolean
- type: string
description: >-
Ad storage consent. Accepts booleans or strings; only `"true"`
(case-insensitive) is treated as true.
default: false
ad_user_data:
oneOf:
- type: boolean
- type: string
description: >-
Ad user data consent. Accepts booleans or strings; only `"true"`
(case-insensitive) is treated as true.
default: false
ad_personalization:
oneOf:
- type: boolean
- type: string
description: >-
Ad personalization consent. Accepts booleans or strings; only
`"true"` (case-insensitive) is treated as true.
default: false
analytics_storage:
oneOf:
- type: boolean
- type: string
description: >-
Analytics storage consent. Accepts booleans or strings; only
`"true"` (case-insensitive) is treated as true.
default: false
Meta:
type: object
properties:
requestId:
type: string
example: req_a1b2c3d4e5f6
timestamp:
type: string
format: date-time
example: '2026-03-10T12:00:00.000Z'
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
description: Error code
example: VALIDATION_ERROR
message:
type: string
description: Human readable error message
example: Human readable error message
details:
type: object
description: Optional additional error details
meta:
$ref: '#/components/schemas/Meta'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API key for authentication
````