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 '
{
  "id": "lead_abc123",
  "email": "john@example.com",
  "phone": "+1234567890",
  "status": "won",
  "changedTo": "won",
  "value": 5000,
  "note": "<string>",
  "lossReason": "<string>"
}
'
{
  "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 id, email, or phone (in that priority order). At least one identifier (id, email, or phone) is required.

​
Request Body

FieldTypeRequiredDescription
idstringNo*Lead ID (highest priority match)
emailstringNo*Lead email (second priority match)
phonestringNo*Lead phone (third priority match)
statusstringNoNew status: qualified, won, or lost
changedTostringNoLegacy alias for status (same values)
valuenumber | stringNoLead value (strings are auto-converted to numbers)
notestringNoNote to attach to the lead
lossReasonstringNoReason for loss (only used when status is lost)
* At least one of 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

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

{
  "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

StatusCodeDescription
400VALIDATION_ERRORInvalid JSON or missing identifier
401UNAUTHORIZEDMissing or invalid API key
404NOT_FOUNDNo lead found matching the provided identifiers
409CONFLICTMultiple leads match; provide a more specific identifier
500INTERNAL_ERRORServer error

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.

At least one of id, email, or phone is required as an identifier.

​
id
string

Lead ID (highest priority match)

Example:

"lead_abc123"

​
email
string<email>

Lead email (second priority match)

Example:

"john@example.com"

​
phone
string

Lead phone (third priority match)

Example:

"+1234567890"

​
status
enum<string>

New status. Takes precedence over changedTo if both are provided.

Available options:
qualified,
won,
lost
Example:

"won"

​
changedTo
enum<string>

Legacy alias for status (same values).

Available options:
qualified,
won,
lost
Example:

"won"

​
value

Lead value. Strings are auto-converted to numbers.

Example:

5000

​
note
string

Note to attach to the lead

​
lossReason
string

Reason for loss (only used when status is lost)

Response

Lead updated successfully

​
success
boolean
Example:

true

​
data
object
​
meta
object