curl --request POST \
--url https://api.naturalead.ai/api/leads \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"phone": "<string>",
"name": "<string>",
"email": "<string>",
"tags": [
"<string>"
]
}
'import requests
url = "https://api.naturalead.ai/api/leads"
payload = {
"phone": "<string>",
"name": "<string>",
"email": "<string>",
"tags": ["<string>"]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone: '<string>', name: '<string>', email: '<string>', tags: ['<string>']})
};
fetch('https://api.naturalead.ai/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://api.naturalead.ai/api/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '<string>',
'name' => '<string>',
'email' => '<string>',
'tags' => [
'<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"
payload := strings.NewReader("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.naturalead.ai/api/leads")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\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": "phone is required"
}{
"error": "A lead with this phone number already exists"
}{
"error": "<string>"
}Create Lead
Creates a new lead for the account. Phone number must be unique
within the account.
Requires leads:import permission.
curl --request POST \
--url https://api.naturalead.ai/api/leads \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"phone": "<string>",
"name": "<string>",
"email": "<string>",
"tags": [
"<string>"
]
}
'import requests
url = "https://api.naturalead.ai/api/leads"
payload = {
"phone": "<string>",
"name": "<string>",
"email": "<string>",
"tags": ["<string>"]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone: '<string>', name: '<string>', email: '<string>', tags: ['<string>']})
};
fetch('https://api.naturalead.ai/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://api.naturalead.ai/api/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '<string>',
'name' => '<string>',
'email' => '<string>',
'tags' => [
'<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"
payload := strings.NewReader("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.naturalead.ai/api/leads")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ]\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": "phone is required"
}{
"error": "A lead with this phone number already exists"
}{
"error": "<string>"
}Authorizations
API key prefixed with nl_live_ or nl_test_
Response
Lead created
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.