Create Lead
curl --request POST \
--url https://api.buena.ai/api/v2/leads \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"company": "<string>",
"title": "<string>",
"phone": "<string>",
"linkedinUrl": "<string>",
"industry": "<string>",
"location": "<string>",
"source": "<string>",
"tags": [
{}
],
"customFields": {}
}
'import requests
url = "https://api.buena.ai/api/v2/leads"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"company": "<string>",
"title": "<string>",
"phone": "<string>",
"linkedinUrl": "<string>",
"industry": "<string>",
"location": "<string>",
"source": "<string>",
"tags": [{}],
"customFields": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
email: '<string>',
company: '<string>',
title: '<string>',
phone: '<string>',
linkedinUrl: '<string>',
industry: '<string>',
location: '<string>',
source: '<string>',
tags: [{}],
customFields: {}
})
};
fetch('https://api.buena.ai/api/v2/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.buena.ai/api/v2/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([
'firstName' => '<string>',
'lastName' => '<string>',
'email' => '<string>',
'company' => '<string>',
'title' => '<string>',
'phone' => '<string>',
'linkedinUrl' => '<string>',
'industry' => '<string>',
'location' => '<string>',
'source' => '<string>',
'tags' => [
[
]
],
'customFields' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"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.buena.ai/api/v2/leads"
payload := strings.NewReader("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "<content-type>")
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.buena.ai/api/v2/leads")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.buena.ai/api/v2/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"] = '<content-type>'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "lead_123abc",
"firstName": "John",
"lastName": "Doe",
"email": "john@techcorp.com",
"company": "Tech Corp",
"title": "Software Engineer",
"phone": "+1-555-123-4567",
"linkedinUrl": "https://linkedin.com/in/johndoe",
"source": "linkedin",
"status": "new",
"tags": [],
"customFields": {},
"createdAt": "2024-01-20T15:30:00Z",
"updatedAt": "2024-01-20T15:30:00Z"
}
}
Lead Management
Create Lead
Create a new lead in your database
POST
/
api
/
v2
/
leads
Create Lead
curl --request POST \
--url https://api.buena.ai/api/v2/leads \
--header 'Content-Type: <content-type>' \
--header 'x-api-key: <api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"company": "<string>",
"title": "<string>",
"phone": "<string>",
"linkedinUrl": "<string>",
"industry": "<string>",
"location": "<string>",
"source": "<string>",
"tags": [
{}
],
"customFields": {}
}
'import requests
url = "https://api.buena.ai/api/v2/leads"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"company": "<string>",
"title": "<string>",
"phone": "<string>",
"linkedinUrl": "<string>",
"industry": "<string>",
"location": "<string>",
"source": "<string>",
"tags": [{}],
"customFields": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
email: '<string>',
company: '<string>',
title: '<string>',
phone: '<string>',
linkedinUrl: '<string>',
industry: '<string>',
location: '<string>',
source: '<string>',
tags: [{}],
customFields: {}
})
};
fetch('https://api.buena.ai/api/v2/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.buena.ai/api/v2/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([
'firstName' => '<string>',
'lastName' => '<string>',
'email' => '<string>',
'company' => '<string>',
'title' => '<string>',
'phone' => '<string>',
'linkedinUrl' => '<string>',
'industry' => '<string>',
'location' => '<string>',
'source' => '<string>',
'tags' => [
[
]
],
'customFields' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"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.buena.ai/api/v2/leads"
payload := strings.NewReader("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "<content-type>")
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.buena.ai/api/v2/leads")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.buena.ai/api/v2/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"] = '<content-type>'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"email\": \"<string>\",\n \"company\": \"<string>\",\n \"title\": \"<string>\",\n \"phone\": \"<string>\",\n \"linkedinUrl\": \"<string>\",\n \"industry\": \"<string>\",\n \"location\": \"<string>\",\n \"source\": \"<string>\",\n \"tags\": [\n {}\n ],\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "lead_123abc",
"firstName": "John",
"lastName": "Doe",
"email": "john@techcorp.com",
"company": "Tech Corp",
"title": "Software Engineer",
"phone": "+1-555-123-4567",
"linkedinUrl": "https://linkedin.com/in/johndoe",
"source": "linkedin",
"status": "new",
"tags": [],
"customFields": {},
"createdAt": "2024-01-20T15:30:00Z",
"updatedAt": "2024-01-20T15:30:00Z"
}
}
Add a new lead to your database with contact information, company details, and custom attributes. Leads can be created manually or imported from various sources.
Requires the
leads:write permission.Request
Your API key with
leads:write permissionMust be
application/jsonBody Parameters
Lead’s first name
Lead’s last name
Primary email address
Company name
Job title
Phone number
LinkedIn profile URL
Industry sector
Geographic location
Lead source (e.g., “website”, “referral”, “linkedin”)
Array of tag strings for categorization
Object containing custom field key-value pairs
Examples
Basic Lead Creation
curl -X POST "https://api.buena.ai/api/v2/leads" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "John",
"lastName": "Doe",
"email": "john@techcorp.com",
"company": "Tech Corp",
"title": "Software Engineer",
"phone": "+1-555-123-4567",
"linkedinUrl": "https://linkedin.com/in/johndoe",
"source": "linkedin"
}'
const response = await fetch("https://api.buena.ai/api/v2/leads", {
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
firstName: "John",
lastName: "Doe",
email: "john@techcorp.com",
company: "Tech Corp",
title: "Software Engineer",
phone: "+1-555-123-4567",
linkedinUrl: "https://linkedin.com/in/johndoe",
source: "linkedin",
}),
});
const data = await response.json();
console.log(data);
import requests
response = requests.post(
'https://api.buena.ai/api/v2/leads',
headers={
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'firstName': 'John',
'lastName': 'Doe',
'email': 'john@techcorp.com',
'company': 'Tech Corp',
'title': 'Software Engineer',
'phone': '+1-555-123-4567',
'linkedinUrl': 'https://linkedin.com/in/johndoe',
'source': 'linkedin'
}
)
print(response.json())
Lead with Custom Fields and Tags
curl -X POST "https://api.buena.ai/api/v2/leads" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Jane",
"lastName": "Smith",
"email": "jane@startup.io",
"company": "Startup Inc",
"title": "CEO",
"industry": "Technology",
"location": "San Francisco, CA",
"source": "referral",
"tags": ["hot-lead", "enterprise", "decision-maker"],
"customFields": {
"companySize": "50-100",
"budget": "100k+",
"timeline": "Q2 2024"
}
}'
const response = await fetch("https://api.buena.ai/api/v2/leads", {
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
firstName: "Jane",
lastName: "Smith",
email: "jane@startup.io",
company: "Startup Inc",
title: "CEO",
industry: "Technology",
location: "San Francisco, CA",
source: "referral",
tags: ["hot-lead", "enterprise", "decision-maker"],
customFields: {
companySize: "50-100",
budget: "100k+",
timeline: "Q2 2024",
},
}),
});
const data = await response.json();
console.log(data);
Response
Always
true for successful requestsThe created lead object
Show Lead Object
Show Lead Object
Unique identifier for the lead
Lead’s first name
Lead’s last name
Primary email address
Company name
Job title
Lead status (e.g., “new”, “contacted”, “qualified”)
ISO 8601 timestamp when the lead was created
ISO 8601 timestamp when the lead was last updated
{
"success": true,
"data": {
"id": "lead_123abc",
"firstName": "John",
"lastName": "Doe",
"email": "john@techcorp.com",
"company": "Tech Corp",
"title": "Software Engineer",
"phone": "+1-555-123-4567",
"linkedinUrl": "https://linkedin.com/in/johndoe",
"source": "linkedin",
"status": "new",
"tags": [],
"customFields": {},
"createdAt": "2024-01-20T15:30:00Z",
"updatedAt": "2024-01-20T15:30:00Z"
}
}
Next Steps
Update Lead
Modify lead information
Enrich Lead
Add enriched data to leads
List Leads
View all your leads
Lead Management
Learn lead management best practices
⌘I

