Update Lead
Copy
curl --request PATCH \
--url https://octanist.com/api/leads \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"id": "lead_abc123",
"email": "john@example.com",
"phone": "+1234567890",
"status": "won",
"changedTo": "won",
"value": 5000,
"note": "<string>",
"lossReason": "<string>"
}
'Copy
{
"success": true,
"data": {
"leadId": "lead_abc123",
"leadsUpdated": 1,
"message": "Lead updated successfully"
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}Leads
Update Lead
Update an existing lead
PATCH
/
api
/
leads
Update Lead
Copy
curl --request PATCH \
--url https://octanist.com/api/leads \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"id": "lead_abc123",
"email": "john@example.com",
"phone": "+1234567890",
"status": "won",
"changedTo": "won",
"value": 5000,
"note": "<string>",
"lossReason": "<string>"
}
'Copy
{
"success": true,
"data": {
"leadId": "lead_abc123",
"leadsUpdated": 1,
"message": "Lead updated successfully"
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}Update an existing lead. Matches leads by
* At least one of
id, email, or phone (in that priority order).
At least one identifier (id, email, or phone) is required.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No* | Lead ID (highest priority match) |
email | string | No* | Lead email (second priority match) |
phone | string | No* | Lead phone (third priority match) |
status | string | No | New status: qualified, won, or lost |
changedTo | string | No | Legacy alias for status (same values) |
value | number | string | No | Lead value (strings are auto-converted to numbers) |
note | string | No | Note to attach to the lead |
lossReason | string | No | Reason for loss (only used when status is lost) |
id, email, or phone is required.
When both status and changedTo are provided, status takes precedence.
When matching by email or phone, multiple leads may match. If your organization settings allow bulk updates, all matching leads are updated. Otherwise, a 409 CONFLICT error is returned.
Example Request
Copy
curl -X PATCH \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"email": "john@example.com",
"status": "won",
"value": 5000
}' \
"https://octanist.com/api/leads"
Example Response
Copy
{
"success": true,
"data": {
"leadId": "lead_abc123",
"leadsUpdated": 1,
"message": "Lead updated successfully"
},
"meta": {
"requestId": "req_a1b2c3d4e5f6",
"timestamp": "2026-03-10T12:00:00.000Z"
}
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid JSON or missing identifier |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 404 | NOT_FOUND | No lead found matching the provided identifiers |
| 409 | CONFLICT | Multiple leads match; provide a more specific identifier |
| 500 | INTERNAL_ERROR | Server error |
Authorizations
API key for authentication
Body
application/json
Lead update data. At least one of id, email, or phone is required.
At least one of id, email, or phone is required as an identifier.
Lead ID (highest priority match)
Example:
"lead_abc123"
Lead email (second priority match)
Example:
"john@example.com"
Lead phone (third priority match)
Example:
"+1234567890"
New status. Takes precedence over changedTo if both are provided.
Available options:
qualified, won, lost Example:
"won"
Legacy alias for status (same values).
Available options:
qualified, won, lost Example:
"won"
Lead value. Strings are auto-converted to numbers.
Example:
5000
Note to attach to the lead
Reason for loss (only used when status is lost)
⌘I