Search for people using natural language queries with the Nyne Search API. Find professionals by role, company, location, industry, or any combination. Supports custom filters, AI relevance scoring, contact enrichment (emails + phones), pagination, and three search tiers (light, medium, premium). Async with polling.
Instrucciones de origen · Vista previa de solo lectura
name
nyne-search
description
Search for people using natural language queries with the Nyne Search API. Find professionals by role, company, location, industry, or any combination. Supports custom filters, AI relevance scoring, contact enrichment (emails + phones), pagination, and three search tiers (light, medium, premium). Async with polling.
Nyne Search Skill
Search for people using natural language queries. Find professionals by role, company, location, industry, or any combination. Returns matching profiles with contact info, work history, education, and optional AI relevance scoring.
Important: This API is async. You POST to submit, get a request_id, then poll GET until status: "completed". Light searches complete in 3-40 seconds; premium searches take 30-300 seconds.
Agent Instructions
When presenting search results to the user, show all returned data for each person. Walk through:
Result count — total_stored, total_estimate, has_more, credits_charged
Each person — displayname, headline, bio, location, gender, estimated_age, total_experience_years, is_decision_maker
Contact info — best_business_email, best_personal_email, altemails, fullphone (if show_emails/show_phone_numbers were enabled)
Social profiles — LinkedIn URL, username, connections, followers
Work history — all organizations with title, dates, company details (industries, num_employees, funding, technologies)
Education — schools with degree, major, dates; note is_top_universities flag
The API response can contain control characters in JSON string values that break jq. All examples use a nyne_parse helper that cleans and re-encodes JSON via python3. Define it once per session:
nyne_parse() {
python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
Quick Start
Search for people by natural language query and poll until complete:
nyne_parse() {
python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
# Submit search request
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Software engineers at Google in San Francisco", "limit": 10, "type": "premium", "show_emails": true}' | nyne_parse > /tmp/nyne_search.json
STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
if [ "$STATUS" = "completed" ]; thenecho"Search completed immediately."
jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
else
REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_search.json)
echo"Request submitted: $REQUEST_ID (status: $STATUS)"# Poll until complete (checks every 5s, times out after 10 min)
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 600 ]; do
curl -s "https://api.nyne.ai/person/search?request_id=$REQUEST_ID" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_search.json
STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
echo"Status: $STATUS ($SECONDS_WAITED seconds elapsed)"if [ "$STATUS" = "completed" ]; then
jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
breakelif [ "$STATUS" = "failed" ]; thenecho"Search failed."
jq . /tmp/nyne_search.json
breakfisleep 5
SECONDS_WAITED=$((SECONDS_WAITED + 5))
doneif [ $SECONDS_WAITED -ge 600 ]; thenecho"Timed out after 10 minutes. Resume polling with request_id: $REQUEST_ID"fifi
Starting position, 0-indexed (max 999). offset + limit must be ≤ 1000
show_emails
boolean
false
Include email addresses in results (+2 credits). Significantly increases latency — search will take longer to complete as emails are enriched per result
show_phone_numbers
boolean
false
Include phone numbers in results (+14 credits). Significantly increases latency — search will take longer to complete as phone numbers are enriched per result
require_emails
boolean
false
Only return profiles that have email addresses (+1 credit)
require_phone_numbers
boolean
false
Only return profiles that have phone numbers (+1 credit)
require_phones_or_emails
boolean
false
Only return profiles with either phone or email (+1 credit)
insights
boolean
false
AI-generated insights per result explaining match relevance (+1 credit per result). Not available for light type
profile_scoring
boolean
false
Include AI relevance score (0-1) per result (+1 credit)
high_freshness
boolean
false
Prioritize recently updated profiles (+2 credits). Not available for light type
force_new
boolean
false
Force fresh search, ignore cached results
custom_filters
object
omit
Structured filters for precise targeting (see Custom Filters below)
callback_url
string
omit
Webhook URL for async results delivery
Custom Filters
Pass as a custom_filters object to narrow results beyond the natural language query.
Array fields (pass as arrays of strings):
Filter
Description
locations
Geographic locations (e.g., ["San Francisco", "New York"])
languages
Languages spoken (e.g., ["English", "Spanish"])
titles
Job titles (e.g., ["CTO", "VP Engineering"])
industries
Industry sectors (e.g., ["Technology", "Healthcare"])
companies
Company names, current or past (e.g., ["Google", "Meta"])
Note: The POST may return status: "completed" immediately (especially for cached or light searches) or status: "processing" requiring polling. Always check the status.
{"name":"Windfall Bio","title":"Vice President of Software Engineering","startDate":"2024-08-01","endDate":null,"location":"San Mateo, California, United States","company_website":"http://www.windfall.bio","company_linkedin_url":"https://www.linkedin.com/company/windfallbio","company_domain":"windfall.bio","industries":["Manufacturing"],"num_employees":37,"num_employees_range":"11-50","is_startup":true,"is_b2b":true,"is_b2c":false,"is_saas":false,"founded_in":2022,"latest_funding_round":"Series A","latest_funding_amount":28000000,"funding_total_usd":37000000,"annual_revenue":345000,"specialties":["methane","climate","agtech"],"technologies":["Google Analytics","AWS Lambda","Webflow"],"companyDesc":"...","logo_url":"..."}
Organizations include rich company intelligence: funding data, tech stack, employee counts, and B2B/B2C/SaaS flags. Not all fields are present for every organization.
Response Metadata Fields
Field
Type
Description
total_stored
integer
Number of results stored from this search
total_estimate
integer
Estimated total matching profiles
has_more
boolean
Whether more results are available for pagination
next_cursor
string
Opaque pagination token for next page (present when has_more is true)
from_cache
boolean
Whether results came from cache (30-day TTL)
credits_charged
integer
Total credits charged for this request
offset
integer
Current offset in result set
limit
integer
Results per page
Useful jq Filters
After polling completes, the clean response is at /tmp/nyne_search.json:
Basic search with fast results in 3-40 seconds. Best for quick lookups when you need a broad list of names and don't need deep profile data. AI features (insights, high_freshness) are NOT available for light type. Profile scoring is available.
{"query":"Software engineers at Google","type":"light","limit":50}
Smart Search — type: "medium"
Balanced tier between speed and quality. Use when you want better matching than light but don't need the full depth of premium. Supports all AI features.
{"query":"Engineering managers in fintech","type":"medium","limit":25}
Pro Search — type: "premium" (5 credits per result)
Comprehensive search taking 30-300 seconds. Best quality results with deepest profile matching. Required for maximum-quality insights and high_freshness results. Use when result quality matters more than speed.
{"query":"AI researchers at top universities","type":"premium","limit":10,"insights":true,"profile_scoring":true}
AI-Powered Analysis Features
These features add intelligence on top of search results. Insights and High Freshness are NOT available for light type searches — use medium or premium.
Query Insights (insights: true, +1 credit per result)
AI-generated analysis for each result explaining why this person matches your search query. Returns structured reasoning about the match relevance — how their background, role, and experience align with what you're looking for. Invaluable for qualifying leads or evaluating candidates at scale. Use when you need to understand the "why" behind each match, not just the "who".
{"query":"AI researchers in healthcare","type":"premium","insights":true,"limit":10}
AI relevance scoring that assigns each result a score from 0 to 1, where 1.0 is a perfect match. Use to rank and prioritize results by relevance. Works with all search tiers including light. Combine with insights for both a score and an explanation.
{"query":"Senior engineers at fintech startups","profile_scoring":true,"limit":25}
High Freshness (high_freshness: true, +2 credits)
Prioritizes profiles that have been recently updated — people who recently changed jobs, updated their LinkedIn, or have fresh activity. Use when recency matters: hiring recently active candidates, targeting people who just moved to a new role, or finding profiles with current contact info. Not available for light type.
{"query":"Product managers who recently changed jobs","type":"premium","high_freshness":true,"show_emails":true}
Combining AI Features
Stack insights + scoring + freshness for maximum intelligence:
{"query":"VP of Engineering at Series B startups in San Francisco","type":"premium","insights":true,"profile_scoring":true,"high_freshness":true,"show_emails":true,"limit":10}
Credit Costs
Credits are charged based on features used per request. Pagination within cached results is free.
Feature
Credits
Description
Fast Search (type: "light")
1
Basic search, fastest response (3-40 seconds)
Pro Search (type: "premium")
5
Comprehensive search, best quality (30-300 seconds)
Smart Ranking (profile_scoring, boolean)
1
AI-powered relevance scoring of results
Candidate Insights (insights, boolean)
1
AI-generated insights about each result
Realtime Profiles (high_freshness, boolean)
2
Prioritize recently updated profiles
Filter Without Contact Data
1
Search without email/phone enrichment
Enrich Phones (show_phone_numbers, boolean)
14
Include phone numbers in results. Significantly increases latency
Enrich Emails (show_emails, boolean)
2
Include email addresses in results. Significantly increases latency
Require Emails (require_emails, boolean)
1
Only return profiles with email addresses
Require Phones (require_phone_numbers, boolean)
1
Only return profiles with phone numbers
Require Contact Info (require_phones_or_emails, boolean)
