curl --request PATCH \
--url https://api.naturalead.ai/api/conversations/{id}/status \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '{}'import requests
url = "https://api.naturalead.ai/api/conversations/{id}/status"
payload = {}
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({})
};
fetch('https://api.naturalead.ai/api/conversations/{id}/status', 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/conversations/{id}/status",
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([
]),
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/conversations/{id}/status"
payload := strings.NewReader("{}")
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/conversations/{id}/status")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/conversations/{id}/status")
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 = "{}"
response = http.request(request)
puts response.read_body{
"_id": "665f1a2b3c4d5e6f7a8b9c0d",
"leadId": "<string>",
"accountId": "<string>",
"agentConfigId": "<string>",
"channel": "whatsapp",
"leadPhone": "<string>",
"status": "active",
"currentStageIndex": 123,
"messages": [
{
"role": "agent",
"content": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"agentConfigId": "<string>"
}
],
"messageCount": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"campaignId": "<string>",
"leadEmail": "<string>",
"currentStageName": "<string>",
"summary": "<string>",
"qualificationResult": {
"qualified": true,
"reason": "<string>"
}
}{
"error": "Invalid status. Must be: completed, handed_off, or dropped"
}{
"error": "Conversation not found"
}{
"error": "<string>"
}Update Conversation Status
Updates the status of a conversation. Only transitions to completed, handed_off, or dropped are allowed. Requires conversations:change_status permission.
curl --request PATCH \
--url https://api.naturalead.ai/api/conversations/{id}/status \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '{}'import requests
url = "https://api.naturalead.ai/api/conversations/{id}/status"
payload = {}
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({})
};
fetch('https://api.naturalead.ai/api/conversations/{id}/status', 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/conversations/{id}/status",
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([
]),
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/conversations/{id}/status"
payload := strings.NewReader("{}")
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/conversations/{id}/status")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/conversations/{id}/status")
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 = "{}"
response = http.request(request)
puts response.read_body{
"_id": "665f1a2b3c4d5e6f7a8b9c0d",
"leadId": "<string>",
"accountId": "<string>",
"agentConfigId": "<string>",
"channel": "whatsapp",
"leadPhone": "<string>",
"status": "active",
"currentStageIndex": 123,
"messages": [
{
"role": "agent",
"content": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"agentConfigId": "<string>"
}
],
"messageCount": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"campaignId": "<string>",
"leadEmail": "<string>",
"currentStageName": "<string>",
"summary": "<string>",
"qualificationResult": {
"qualified": true,
"reason": "<string>"
}
}{
"error": "Invalid status. Must be: completed, handed_off, or dropped"
}{
"error": "Conversation not found"
}{
"error": "<string>"
}Authorizations
API key for programmatic access (format nl_live_* or nl_test_*)
Path Parameters
MongoDB ObjectId of the conversation.
Body
The new status for the conversation.
completed, handed_off, dropped Response
Status updated successfully. Returns the updated conversation.
MongoDB ObjectId of the conversation.
"665f1a2b3c4d5e6f7a8b9c0d"
The ID of the associated lead.
MongoDB ObjectId of the account (tenant).
MongoDB ObjectId of the agent configuration used.
The messaging channel used for this conversation.
whatsapp, telegram, email The lead's phone number.
Current status of the conversation.
active, completed, handed_off, dropped Index of the current conversation stage.
Ordered list of messages in the conversation.
Show child attributes
Show child attributes
Total number of messages in the conversation.
When the conversation was created.
When the conversation was last updated. Filter list results with
updatedAfter / updatedBefore for incremental sync.
MongoDB ObjectId of the campaign, if conversation was started by a campaign.
The lead's email address.
Name of the current conversation stage.
Reserved for an LLM-generated prose brief of the conversation.
Not populated today. For structured key points (budget, timeline,
etc.), use GET /api/preferences/{leadId} (Lead Insights) instead.
Deprecated historical scorecard. New completes do not write this field;
prefer currentStageName (terminal stage) as the journey outcome.
Show child attributes
Show child attributes