# Person Leads API > Find potential leads using natural language descriptions - just describe who you're looking for **Base URL:** `https://api.nyne.ai` **Endpoint:** `https://api.nyne.ai/person/leads` --- ## Overview The Person Leads API uses advanced AI to convert your natural language description into optimized searches across social media platforms. Simply describe the type of people you're looking for, and our system will find relevant leads who have recently posted about related topics. ### How It Works **Step 1:** Describe the type of leads you're looking for in plain English **Step 2:** Our AI analyzes your description and creates optimized search queries **Step 3:** We search across multiple social platforms simultaneously **Step 4:** Results are aggregated, deduplicated, and returned to you ### Example Descriptions - "Marketing directors at SaaS companies who are interested in AI tools" - "Startup founders discussing fundraising or looking for investors" - "HR professionals talking about employee engagement software" - "Real estate agents in California looking for CRM solutions" - "CTOs at fintech companies discussing cloud migration" ### What You Get - **AI-Optimized Search:** Your description is intelligently converted into effective search queries- **Social Media Leads:** Results from people actively posting about relevant topics- **Author Information:** Name, username, profile URL, and headline for each lead- **Post Content:** The actual post that matched your search criteria- **Engagement Metrics:** Likes, comments, and shares for each post- **Recency:** Results are sorted by most recent activity ## Authentication All requests require header authentication: ``` X-API-Key: YOUR_API_KEY X-API-Secret: YOUR_API_SECRET ``` ## Rate Limits | Limit | Value | |-------|-------| | Per Minute | 60 requests | | Per Hour | 1000 requests | | Monthly | Varies by plan | ### Response Headers Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers: | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Active per-minute or per-hour limit | | `X-RateLimit-Remaining` | Remaining requests in the active window | | `X-RateLimit-Reset` | Unix timestamp when the active window resets | | `RateLimit-Limit` | Active per-minute or per-hour limit | | `RateLimit-Remaining` | Remaining requests in the active window | | `RateLimit-Reset` | Seconds until the active window resets | | `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses | Monthly quota responses include quota-specific headers when available: | Header | Description | |--------|-------------| | `X-Quota-Limit` | Monthly request or credit limit | | `X-Quota-Used` | Amount used in the current billing cycle | | `X-Quota-Remaining` | Amount remaining in the current billing cycle | | `X-Quota-Reset` | Unix timestamp when the current billing cycle resets | ## Credit Usage - **Lead Search:** 3 credits per successful search request > Credits are only charged when leads are found. If no leads match your description, no credits are charged. --- ## POST /person/leadsSubmit a lead search request using a natural language description. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `search_description` | string | Yes | A natural language description of the leads you're looking for (10-2000 characters) | | `callback_url` | string | No | URL to receive results asynchronously via HTTP POST | > **Required:** The search_description parameter is required. ### Request Examples **With Advanced Features:** ```json { "search_description": "Startup founders discussing fundraising or seed rounds in the tech industry", "callback_url": "https://yourapp.com/webhook/leads" } ``` **Basic Request:** ```json { "search_description": "Marketing managers at e-commerce companies interested in email automation" } ``` ### Code Examples **cURL:** ```bash curl -X POST https://api.nyne.ai/person/leads \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "search_description": "Marketing managers at e-commerce companies interested in email automation" }' ``` **Python:** ```python import requests import json url = "https://api.nyne.ai/person/leads" headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" } data = { "search_description": "Marketing managers at e-commerce companies interested in email automation" } response = requests.post(url, headers=headers, json=data) result = response.json() print(json.dumps(result, indent=2)) ``` **JavaScript:** ```javascript const url = "https://api.nyne.ai/person/leads"; const headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" }; const data = { search_description: "Marketing managers at e-commerce companies interested in email automation" }; fetch(url, { method: "POST", headers: headers, body: JSON.stringify(data) }) .then(response => response.json()) .then(result => console.log(result)) .catch(error => console.error("Error:", error)); ``` **PHP:** ```php "Marketing managers at e-commerce companies interested in email automation" ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $result = json_decode($response, true); curl_close($ch); echo json_encode($result, JSON_PRETTY_PRINT); ?> ``` ### Response Codes | Code | Description | |------|-------------| | 202 | Request accepted and queued for processing | | 400 | Invalid request parameters | | 401 | Invalid API credentials | | 402 | Insufficient credits | | 429 | Rate limit exceeded | ### Response Example ```json { "success": true, "data": { "request_id": "a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8", "status": "queued", "message": "Lead search request queued for processing." }, "timestamp": "2026-01-14T15:30:00Z" } ``` --- ## GET /person/leads Check the status of a request. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `request_id` | string | Yes | The request ID returned from the POST call | ### Request Example ``` GET /person/leads?request_id=a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8 ``` ### Response Codes | Code | Description | |------|-------------| | 200 | Status retrieved successfully | | 400 | Invalid request parameters | | 401 | Invalid API credentials | | 404 | Request ID not found | ### Response Example ```json { "success": true, "data": { "request_id": "a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8", "status": "completed", "created_on": "2026-01-14T15:30:00", "completed_on": "2026-01-14T15:31:45", "results_count": 15, "results": [ { "platform": "linkedin", "post_url": "https://www.linkedin.com/feed/update/urn:li:activity:123456789", "post_content": "Excited to announce we just closed our Series A! Looking for talented engineers to join our mission...", "post_date": "2026-01-13T10:30:00Z", "author": { "name": "Sarah Chen", "username": "sarahchen", "profile_url": "https://www.linkedin.com/in/sarahchen", "headline": "CEO & Co-founder at TechStartup | Former Google", "image_url": "https://media.licdn.com/dms/image/..." }, "engagement": { "likes": 234, "comments": 45, "shares": 12 } }, { "platform": "twitter", "post_url": "https://x.com/techfounder/status/1234567890", "post_content": "Just raised our seed round! If you're building in AI/ML space and need advice on fundraising, happy to chat...", "post_date": "2026-01-12T14:22:00Z", "author": { "name": "Alex Thompson", "username": "techfounder", "profile_url": "https://x.com/techfounder", "headline": "Building the future of AI | Founder @AIStartup", "image_url": "https://pbs.twimg.com/profile_images/..." }, "engagement": { "likes": 89, "comments": 23, "shares": 15 } } ] }, "timestamp": "2026-01-14T15:32:00Z" } ``` --- ## Response Format All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available: - The status field indicates the current processing stage: pending, analyzing, searching, aggregating, completed, or failed- Each result includes platform, post_url, post_content, post_date, author, and engagement objects- The author object contains name, username, profile_url, headline, and optionally image_url- The engagement object contains likes, comments, and shares as numbers- Results are sorted by most recent activity --- ## Error Codes | HTTP Code | Error Code | Description | |-----------|------------|-------------| | 400 | `missing_parameters` | search_description parameter is required | | 400 | `invalid_search_description` | search_description must be 10-2000 characters | | 400 | `invalid_callback_url` | callback_url must be a valid HTTP or HTTPS URL | | 401 | `invalid_credentials` | API key or secret is incorrect | | 402 | `insufficient_credits` | Not enough credits available | | 404 | `not_found` | Request ID not found | | 429 | `rate_limit_exceeded` | Rate limit exceeded | | 500 | `internal_error` | Internal server error | --- ## Callbacks When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST. ### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 30-second timeout per request- Your endpoint should return HTTP 2xx for success Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry. ### Callback Payload Example ```json { "request_id": "a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8", "status": "completed", "completed": true, "results_count": 15, "results": [ { "platform": "linkedin", "post_url": "https://www.linkedin.com/feed/update/...", "post_content": "...", "post_date": "2026-01-13T10:30:00Z", "author": { "name": "Sarah Chen", "username": "sarahchen", "profile_url": "https://www.linkedin.com/in/sarahchen", "headline": "CEO & Co-founder at TechStartup" }, "engagement": { "likes": 234, "comments": 45, "shares": 12 } } ], "timestamp": "2026-01-14T15:31:45Z" } ``` --- ## Related APIs - **Person Search API** - Structured search with filters -> `https://api.nyne.ai/documentation/person/search` - **Person Discover API** - Keyword-based people discovery -> `https://api.nyne.ai/documentation/person/discover` - **Person Enrichment API** - Enrich lead profiles -> `https://api.nyne.ai/documentation/person/enrichment`