You need to log in to access your API credentials and start using our APIs. Start with our free trial!
Log In & Start Free TrialPerson Leads API
Find potential leads using natural language descriptions - just describe who you're looking for
API Endpoint
https://api.nyne.ai/person/leads
Try the API Playground
Test the API with our interactive playground to make real requests and see live responses.
Launch Person Leads PlaygroundOverview
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.
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
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"
Authentication
All API requests require authentication using your API key and secret. You can authenticate using either HTTP headers (recommended) or query parameters.
X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here
Rate Limits
API usage is controlled by rate limiting mechanisms to ensure fair usage and system stability:
- Per Minute: 60 requests
- Per Hour: 1000 requests
- Monthly: Varies by plan
Credit Usage
API credits are consumed based on successful lead searches:
- Lead Search: 1 credit per successful search request
Credit Efficiency
Credits are only charged when leads are found. If no leads match your description, no credits are charged.
POST /person/leads
Submit a lead search request using a natural language description.
POST /person/leads
Parameters
A natural language description of the leads you're looking for (10-2000 characters)
Example: "Marketing managers at e-commerce companies interested in email automation"
URL to receive results asynchronously via HTTP POST
Example: https://yourapp.com/webhook/leads
Request Example
Response Codes
202 Request accepted and queued for processing
400 Invalid request parameters
401 Invalid API credentials
429 Rate limit exceeded
Response Example (202 Accepted)
GET /person/leads
Check the status and retrieve results of a leads search request.
GET /person/leads?request_id=
Parameters
The request ID returned from the POST call
Example: a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8
Request Example
Response Codes
200 Status retrieved successfully
400 Invalid request parameters
401 Invalid API credentials
404 Request ID not found
Response Example (Completed)
Response Example (Processing)
Response Format
All API responses follow a consistent JSON format:
Status Values
The status field indicates the current processing stage:
- pending - Request received, waiting to process
- analyzing - AI is analyzing your search description
- searching - Executing searches across platforms
- aggregating - Collecting and deduplicating results
- completed - Results ready
- failed - Request failed (see error message)
Lead Result Fields
| Field | Type | Description |
|---|---|---|
| platform | string | Source platform (e.g., "linkedin", "twitter") |
| post_url | string | Direct URL to the original post |
| post_content | string | Text content of the post |
| post_date | string | ISO 8601 timestamp of when the post was created |
| author.name | string | Full display name of the author |
| author.username | string | Platform username/handle |
| author.profile_url | string | URL to the author's profile |
| author.headline | string | Author's bio or headline |
| author.image_url | string | URL to the author's profile image |
| engagement.likes | number | Number of likes/reactions |
| engagement.comments | number | Number of comments |
| engagement.shares | number | Number of shares/reposts |
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 |
| 404 | not_found | Request ID not found |
| 429 | rate_limit_exceeded | Rate limit exceeded |
| 500 | internal_error | Internal server error |
Callback System
When you provide a callback_url, the API will send the leads results to your endpoint via HTTP POST once processing is complete.
Callback Request Format
Callback 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
Open Playground to test the API interactively