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",
  "externalId": "QUOTE-2026-0042",
  "email": "john@example.com",
  "phone": "+1234567890",
  "status": "won",
  "changedTo": "won",
  "value": 5000,
  "note": "<string>",
  "lossReason": "<string>"
}
'

import requests

url = "https://octanist.com/api/leads"

payload = {
    "id": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "email": "john@example.com",
    "phone": "+1234567890",
    "status": "won",
    "changedTo": "won",
    "value": 5000,
    "note": "<string>",
    "lossReason": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: 'lead_abc123',
    externalId: 'QUOTE-2026-0042',
    email: 'john@example.com',
    phone: '+1234567890',
    status: 'won',
    changedTo: 'won',
    value: 5000,
    note: '<string>',
    lossReason: '<string>'
  })
};

fetch('https://octanist.com/api/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://octanist.com/api/leads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => 'lead_abc123',
    'externalId' => 'QUOTE-2026-0042',
    'email' => 'john@example.com',
    'phone' => '+1234567890',
    'status' => 'won',
    'changedTo' => 'won',
    'value' => 5000,
    'note' => '<string>',
    'lossReason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://octanist.com/api/leads"

	payload := strings.NewReader("{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://octanist.com/api/leads")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octanist.com/api/leads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "leadId": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "leadsUpdated": 1,
    "message": "Lead updated successfully"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

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",
  "externalId": "QUOTE-2026-0042",
  "email": "john@example.com",
  "phone": "+1234567890",
  "status": "won",
  "changedTo": "won",
  "value": 5000,
  "note": "<string>",
  "lossReason": "<string>"
}
'

import requests

url = "https://octanist.com/api/leads"

payload = {
    "id": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "email": "john@example.com",
    "phone": "+1234567890",
    "status": "won",
    "changedTo": "won",
    "value": 5000,
    "note": "<string>",
    "lossReason": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: 'lead_abc123',
    externalId: 'QUOTE-2026-0042',
    email: 'john@example.com',
    phone: '+1234567890',
    status: 'won',
    changedTo: 'won',
    value: 5000,
    note: '<string>',
    lossReason: '<string>'
  })
};

fetch('https://octanist.com/api/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://octanist.com/api/leads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => 'lead_abc123',
    'externalId' => 'QUOTE-2026-0042',
    'email' => 'john@example.com',
    'phone' => '+1234567890',
    'status' => 'won',
    'changedTo' => 'won',
    'value' => 5000,
    'note' => '<string>',
    'lossReason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://octanist.com/api/leads"

	payload := strings.NewReader("{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://octanist.com/api/leads")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octanist.com/api/leads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"lead_abc123\",\n  \"externalId\": \"QUOTE-2026-0042\",\n  \"email\": \"john@example.com\",\n  \"phone\": \"+1234567890\",\n  \"status\": \"won\",\n  \"changedTo\": \"won\",\n  \"value\": 5000,\n  \"note\": \"<string>\",\n  \"lossReason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "leadId": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "leadsUpdated": 1,
    "message": "Lead updated successfully"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

Update an existing lead. Matches leads by id, externalId, email, or phone (in that priority order). At least one identifier (id, externalId, email, or phone) is required. email and phone can be sent as a single string or as an array of up to 10 strings. Array values are tried sequentially. Octanist first tries the first email, then the next email, and only moves on to phone values if none of the email values match.

Request Body

Field	Type	Required	Description
`id`	string	No*	Lead ID (highest priority match)
`externalId`	string	No*	Customer-owned lead identifier (second priority match, max 255 characters)
`email`	string \| string[]	No*	Lead email or ordered email candidates (third priority match, max 10)
`phone`	string \| string[]	No*	Lead phone or ordered phone candidates (fourth priority match, max 10)
`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`)

* At least one of id, externalId, email, or phone is required. When both status and changedTo are provided, status takes precedence. When email or phone is an array, values are matched in order and the first value with a match wins. The matching order is:

id, if provided
externalId, if provided
email[0], email[1], and so on
phone[0], phone[1], and so on

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. externalId is a lookup identifier on this endpoint. It does not replace or rotate the external ID stored on the lead.

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 Request With Fallback Identifiers

curl -X PATCH \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": ["primary@example.com", "billing@example.com"],
    "phone": ["+31612345678", "+31687654321"],
    "status": "qualified"
  }' \
  "https://octanist.com/api/leads"

Example Request by External ID

curl -X PATCH \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "QUOTE-2026-0042",
    "status": "won",
    "value": 5000
  }' \
  "https://octanist.com/api/leads"

Example Response

{
  "success": true,
  "data": {
    "leadId": "lead_abc123",
    "externalId": "QUOTE-2026-0042",
    "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

X-API-KEY

string

header

required

API key for authentication

Body

application/json

Lead update data. At least one of id, externalId, email, or phone is required.

At least one of id, externalId, email, or phone is required as an identifier. email and phone can be strings or arrays of up to 10 strings. Identifiers are tried sequentially: id first, then externalId, then email values in order, then phone values in order. externalId is used for lookup and is not changed by this endpoint.

string

Lead ID (highest priority match)

Example:

"lead_abc123"

externalId

string

Customer-owned lead identifier (second priority match). Whitespace is trimmed.

Required string length: 1 - 255

Example:

"QUOTE-2026-0042"

Lead email or ordered email candidates (third priority match). Arrays are tried sequentially.

Example:

"john@example.com"

phone

Lead phone or ordered phone candidates (fourth priority match). Arrays are tried sequentially after all email candidates.

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

Show child attributes

Overview

Leads

Analytics

Other

Update Lead

Request Body

Example Request

Example Request With Fallback Identifiers

Example Request by External ID

Example Response

Error Responses

Authorizations

Body

Response

​Request Body

​Example Request

​Example Request With Fallback Identifiers

​Example Request by External ID

​Example Response

​Error Responses

Authorizations

Body

Response

Request Body

Example Request

Example Request With Fallback Identifiers

Example Request by External ID

Example Response

Error Responses