Leads API

The Leads API allows you to retrieve, filter, and manage your captured leads programmatically.

List All Leads

Retrieve all leads captured by your automations.

Endpoint:

GET /leads

Example Request:

curl -X GET "https://api.lazyspond.com/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "ld_123456789",
      "username": "sarah_fitness",
      "display_name": "Sarah Johnson",
      "trigger_keyword": "GUIDE",
      "trigger_type": "story_reply",
      "captured_at": "2024-03-22T14:30:00Z",
      "profile_picture_url": "https://instagram.com/sarah_fitness/avatar.jpg"
    },
    {
      "id": "ld_987654321",
      "username": "john_coach",
      "display_name": "John Smith",
      "trigger_keyword": "PROMO",
      "trigger_type": "comment",
      "captured_at": "2024-03-22T15:45:00Z",
      "profile_picture_url": "https://instagram.com/john_coach/avatar.jpg"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 250
  }
}

Query Parameters

Pagination

page (integer) — Page number (default: 1)
limit (integer) — Results per page (default: 50, max: 100)

Example:

curl -X GET "https://api.lazyspond.com/v1/leads?page=2&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering

keyword (string) — Filter by trigger keyword
trigger_type (string) — Filter by trigger type (story_reply, comment)
start_date (ISO 8601) — Filter by start date
end_date (ISO 8601) — Filter by end date

Example:

curl -X GET "https://api.lazyspond.com/v1/leads?keyword=GUIDE&trigger_type=story_reply" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting

sort_by (string) — Sort field (captured_at, username, display_name)
sort_order (string) — Sort order (asc, desc)

Example:

curl -X GET "https://api.lazyspond.com/v1/leads?sort_by=captured_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a Specific Lead

Retrieve details about a specific lead.

Endpoint:

GET /leads/{id}

Example Request:

curl -X GET "https://api.lazyspond.com/v1/leads/ld_123456789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": {
    "id": "ld_123456789",
    "username": "sarah_fitness",
    "display_name": "Sarah Johnson",
    "trigger_keyword": "GUIDE",
    "trigger_type": "story_reply",
    "captured_at": "2024-03-22T14:30:00Z",
    "profile_picture_url": "https://instagram.com/sarah_fitness/avatar.jpg",
    "tags": ["hot_lead", "guide_interested"],
    "notes": "Very interested in coaching",
    "status": "new"
  }
}

Create a Lead (Testing)

Create a test lead for development purposes.

Endpoint:

POST /leads

Request Body:

{
  "username": "test_user",
  "display_name": "Test User",
  "trigger_keyword": "GUIDE",
  "trigger_type": "story_reply"
}

Example Request:

curl -X POST "https://api.lazyspond.com/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test_user",
    "display_name": "Test User",
    "trigger_keyword": "GUIDE",
    "trigger_type": "story_reply"
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": "ld_test123456",
    "username": "test_user",
    "display_name": "Test User",
    "trigger_keyword": "GUIDE",
    "trigger_type": "story_reply",
    "captured_at": "2024-03-22T16:00:00Z"
  }
}

Update Lead Tags

Add or remove tags from a lead.

Endpoint:

PUT /leads/{id}/tags

Request Body:

{
  "tags": ["hot_lead", "guide_interested", "follow_up"]
}

Example Request:

curl -X PUT "https://api.lazyspond.com/v1/leads/ld_123456789/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["hot_lead", "guide_interested"]
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": "ld_123456789",
    "tags": ["hot_lead", "guide_interested"]
  }
}

Update Lead Status

Update the status of a lead.

Endpoint:

PUT /leads/{id}/status

Request Body:

{
  "status": "qualified"
}

Valid Statuses:

new
contacted
interested
qualified
converted
inactive

Example Request:

curl -X PUT "https://api.lazyspond.com/v1/leads/ld_123456789/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified"
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": "ld_123456789",
    "status": "qualified"
  }
}

Add Note to Lead

Add a note to a lead.

Endpoint:

POST /leads/{id}/notes

Request Body:

{
  "note": "Very interested in pricing. Follow up next week."
}

Example Request:

curl -X POST "https://api.lazyspond.com/v1/leads/ld_123456789/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Very interested in pricing. Follow up next week."
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": "ld_123456789",
    "note": "Very interested in pricing. Follow up next week.",
    "added_at": "2024-03-22T16:30:00Z"
  }
}

Export Leads

Export leads as CSV.

Endpoint:

GET /leads/export

Query Parameters:

format (string) — Export format (csv, json)
keyword (string) — Filter by keyword
start_date (ISO 8601) — Filter by start date
end_date (ISO 8601) — Filter by end date

Example Request:

curl -X GET "https://api.lazyspond.com/v1/leads/export?format=csv&keyword=GUIDE" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o leads.csv

Response Fields

Field	Type	Description
`id`	string	Unique lead ID
`username`	string	Instagram handle (without @)
`display_name`	string	Instagram display name
`trigger_keyword`	string	Keyword that was triggered
`trigger_type`	string	"story_reply" or "comment"
`captured_at`	string	ISO 8601 timestamp
`profile_picture_url`	string	URL to profile picture
`tags`	array	Custom tags
`status`	string	Lead status
`notes`	array	Notes added to lead

Error Responses

Lead Not Found

{
  "success": false,
  "error": "Lead not found"
}

Invalid Parameters

{
  "success": false,
  "error": "Invalid keyword parameter"
}

Code Examples

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.lazyspond.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Get all leads
response = requests.get(f"{BASE_URL}/leads", headers=headers)
leads = response.json()['data']

# Get leads from specific keyword
response = requests.get(
    f"{BASE_URL}/leads?keyword=GUIDE",
    headers=headers
)
guide_leads = response.json()['data']

# Get specific lead
response = requests.get(
    f"{BASE_URL}/leads/ld_123456789",
    headers=headers
)
lead = response.json()['data']

# Update lead status
response = requests.put(
    f"{BASE_URL}/leads/ld_123456789/status",
    headers=headers,
    json={"status": "qualified"}
)

JavaScript

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.lazyspond.com/v1";

const headers = {
  "Authorization": `Bearer ${API_KEY}`
};

// Get all leads
fetch(`${BASE_URL}/leads`, { headers })
  .then(res => res.json())
  .then(data => console.log(data.data));

// Get leads from specific keyword
fetch(`${BASE_URL}/leads?keyword=GUIDE`, { headers })
  .then(res => res.json())
  .then(data => console.log(data.data));

// Update lead status
fetch(`${BASE_URL}/leads/ld_123456789/status`, {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ status: "qualified" })
})
  .then(res => res.json())
  .then(data => console.log(data.data));

Next Steps

Manage automations: See Automations API
Get account info: See Account API
API basics: See API Getting Started