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: <x-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": {}
}'
{
  "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

​
x-api-key
string
required
Your API key with leads:write permission
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
firstName
string
required
Lead’s first name
​
lastName
string
required
Lead’s last name
​
email
string
required
Primary email address
​
company
string
Company name
​
title
string
Job title
​
phone
string
Phone number
​
linkedinUrl
string
LinkedIn profile URL
​
industry
string
Industry sector
​
location
string
Geographic location
​
source
string
Lead source (e.g., “website”, “referral”, “linkedin”)
​
tags
array
Array of tag strings for categorization
​
customFields
object
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"
  }'

​
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"
    }
  }'

​
Response

​
success
boolean
Always true for successful requests
​
data
object
The created lead object
{
  "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