curl --request PATCH \
--url https://api.naturalead.ai/api/leads/{id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"assignedAgentId": "<string>"
}
'import requests
url = "https://api.naturalead.ai/api/leads/{id}"
payload = { "assignedAgentId": "<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({assignedAgentId: '<string>'})
};
fetch('https://api.naturalead.ai/api/leads/{id}', 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://api.naturalead.ai/api/leads/{id}",
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([
'assignedAgentId' => '<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://api.naturalead.ai/api/leads/{id}"
payload := strings.NewReader("{\n \"assignedAgentId\": \"<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://api.naturalead.ai/api/leads/{id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"assignedAgentId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/leads/{id}")
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 \"assignedAgentId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"name": "<string>",
"phone": "<string>",
"email": "",
"status": "new",
"accountId": "<string>",
"source": "api",
"tags": [
"<string>"
],
"assignedAgentId": "<string>",
"abTestId": "<string>",
"agentAssignedBy": "auto",
"customFields": {},
"lastContactedAt": "2023-11-07T05:31:56Z",
"importBatchId": "<string>",
"externalId": "<string>",
"currentStage": {
"name": "<string>",
"index": 123,
"total": 123,
"conversationId": "<string>",
"conversationStatus": "<string>",
"agentConfigId": "<string>",
"agentName": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>"
}{
"error": "Lead not found"
}Update Lead
Updates lead fields such as outreach status (new | contacted) or assigned agent.
Journey position is not set via lead status — it lives on the conversation stage.
Requires leads:import permission.
curl --request PATCH \
--url https://api.naturalead.ai/api/leads/{id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"assignedAgentId": "<string>"
}
'import requests
url = "https://api.naturalead.ai/api/leads/{id}"
payload = { "assignedAgentId": "<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({assignedAgentId: '<string>'})
};
fetch('https://api.naturalead.ai/api/leads/{id}', 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://api.naturalead.ai/api/leads/{id}",
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([
'assignedAgentId' => '<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://api.naturalead.ai/api/leads/{id}"
payload := strings.NewReader("{\n \"assignedAgentId\": \"<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://api.naturalead.ai/api/leads/{id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"assignedAgentId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/leads/{id}")
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 \"assignedAgentId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"name": "<string>",
"phone": "<string>",
"email": "",
"status": "new",
"accountId": "<string>",
"source": "api",
"tags": [
"<string>"
],
"assignedAgentId": "<string>",
"abTestId": "<string>",
"agentAssignedBy": "auto",
"customFields": {},
"lastContactedAt": "2023-11-07T05:31:56Z",
"importBatchId": "<string>",
"externalId": "<string>",
"currentStage": {
"name": "<string>",
"index": 123,
"total": 123,
"conversationId": "<string>",
"conversationStatus": "<string>",
"agentConfigId": "<string>",
"agentName": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>"
}{
"error": "Lead not found"
}Authorizations
API key prefixed with nl_live_ or nl_test_
Path Parameters
Account-scoped sequential lead ID
Body
Response
Updated lead
Sequential, account-scoped identifier
Unique per account
Outreach I/O state for the lead — whether Naturalead has performed contact
yet. This is not journey position. Journey position lives on the
conversation as currentStage / currentStageName.
new, contacted ObjectId reference to AgentConfig
ObjectId reference to AbTest
manual, ab_test, auto Key-value string map of custom fields
Show child attributes
Show child attributes
Present on list responses enriched with the latest conversation stage
Show child attributes
Show child attributes
Last modification time. Also bumped when related conversation
activity occurs, so incremental polls with updatedAfter see
conversation changes.