Skip to main content
PATCH
/
api
/
leads
Update Lead
curl --request PATCH \
  --url https://octanist.com/api/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "changedTo": "won",
  "id": "lead_123",
  "email": "[email protected]",
  "phone": "+1234567890",
  "value": 10000,
  "note": "Closed via phone call",
  "alsoQualified": true
}
'
{
  "success": true,
  "leadId": "lead_123",
  "status": "won"
}
Update a lead’s status, value, or note. You can find leads by ID, email, or phone number.

​
Finding Leads

Provide at least one identifier:
  • id - Lead ID (most efficient)
  • email - Lead email address
  • phone - Lead phone number
If multiple identifiers are provided, the system will use them in order of preference: ID → email → phone.

​
Status Changes

​
Mark as Won

{
  "id": "lead_123",
  "changedTo": "won",
  "value": 15000,
  "note": "Closed deal - annual subscription",
  "alsoQualified": true
}
Requirements:
  • Must include value (lead value)
  • Lead must have a currency (set during creation or previous update)
  • Set alsoQualified: true to also mark the lead as qualified

​
Mark as Qualified

{
  "email": "[email protected]",
  "changedTo": "qualified",
  "value": 5000,
  "note": "Qualified during discovery call"
}
Requirements:
  • Must include value (lead value)

​
Mark as Lost

{
  "phone": "+1234567890",
  "changedTo": "lost",
  "note": "Not interested at this time"
}
Requirements:
  • No additional requirements

​
Example Usage

​
Update by lead ID

curl -X PATCH "https://octanist.com/api/leads" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "lead_123",
    "changedTo": "won",
    "value": 10000,
    "note": "Closed via phone call"
  }'

​
Find and update by email

curl -X PATCH "https://octanist.com/api/leads" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "changedTo": "qualified",
    "value": 5000,
    "note": "Qualified during demo"
  }'

​
Response

Returns success confirmation with lead details: 
{
  "success": true,
  "leadId": "lead_123",
  "status": "won"
}
If the lead is not found: 
{
  "success": false,
  "message": "Lead not found"
}

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Body

application/json

Lead update data

At least one of id, email, or phone is required

​
changedTo
enum<string>
required

New status

Available options:
won,
lost,
qualified
Example:

"won"

​
id
string

Lead ID

Example:

"lead_123"

​
email
string<email>

Lead email (used to find lead if no ID)

Example:

"[email protected]"

​
phone
string

Lead phone (used to find lead if no ID or email)

Example:

"+1234567890"

​
value

Lead value (required for won and qualified status)

Example:

10000

​
note
string

Update the lead's note

Example:

"Closed via phone call"

​
alsoQualified
boolean
default:false

When changedTo is won, also mark as qualified

Example:

true

Response

Lead updated successfully

​
success
boolean
Example:

true

​
leadId
string
Example:

"lead_123"

​
status
string
Example:

"won"