Please Log In

You need to log in to access your API credentials and start using our APIs. Start with our free trial!

Log In & Start Free Trial

Person 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 Playground

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.

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.

Header Authentication (Recommended)
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

search_description (string, required)
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"
callback_url (string, optional)
URL to receive results asynchronously via HTTP POST
Example: https://yourapp.com/webhook/leads

Request Example

{ "search_description": "Startup founders discussing fundraising or seed rounds in the tech industry", "callback_url": "https://yourapp.com/webhook/leads" }

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)

{ "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 and retrieve results of a leads search request.

GET /person/leads?request_id=

Parameters

request_id (string, required)
The request ID returned from the POST call
Example: a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8

Request Example

GET /person/leads?request_id=a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8

Response Codes

200 Status retrieved successfully

400 Invalid request parameters

401 Invalid API credentials

404 Request ID not found

Response Example (Completed)

{ "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 Example (Processing)

{ "success": true, "data": { "request_id": "a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8", "status": "searching", "created_on": "2026-01-14T15:30:00" }, "timestamp": "2026-01-14T15:30:30Z" }

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

{ "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" }

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
Important: Your callback endpoint should respond with HTTP 200-299 to indicate successful receipt. Any other response code will trigger a retry.

Open Playground to test the API interactively