POST
/
api
/
v2
/
leads
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": {}
}'
{
  "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