# Deep Research API > Generate a comprehensive person intelligence dossier combining enrichment data, social analysis, article mentions, and AI-powered insights in a single API call **Base URL:** `https://api.nyne.ai` **Endpoint:** `https://api.nyne.ai/person/deep-research` --- ## Overview The Deep Research API generates a comprehensive person intelligence report by combining multiple data sources with AI-powered analysis. Provide an email address, phone number, social media URL(s), or a person's name with company/city, and receive enrichment data, social following patterns, article mentions, and an LLM-generated 13-section dossier in a single API call. ### How It Works 1. **Data Collection (parallel):** Enrichment lookup, social following fetch (Twitter + Instagram), and article search all run simultaneously 2. **Batch Analysis (parallel):** Following accounts split into groups of ~75 and analyzed by AI for patterns, interests, and relationships (up to 7 parallel AI calls) 3. **Cluster Analysis (parallel):** 5 specialized AI analyses run simultaneously — Sports & Fitness, Entertainment & Culture, Causes & Values, Personal Network, Hidden Interests 4. **Synthesis:** Final AI call combines all data into a 13-section intelligence dossier ### What You Get - **Enrichment Data:** Demographics, career history, social profiles, contact info- **Social Following:** Twitter and Instagram following lists (up to 500 each)- **Article Search:** Press mentions, interviews, podcasts, news articles- **AI Dossier:** Comprehensive LLM-generated 13-section intelligence report ## 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 - **Deep Research:** credits per request (includes enrichment, social following, article search, and AI dossier) > Credits are charged when the research request is accepted (HTTP 202). The flat fee covers all sub-tasks: enrichment, social following, article search, and AI dossier generation. --- ## POST /person/deep-researchSubmit a deep research request on a person. Returns a request_id for polling. Processing takes 2-5 minutes. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | string | No | Email address to research | | `phone` | string | No | Phone number to research (E.164 format preferred, e.g., +15551234567) | | `social_media_url` | string | string[] | No | LinkedIn, Twitter/X, or Instagram profile URL. Pass a single URL string or an array of up to 3 URLs (one per platform) for faster results. | | `name` | string | No | Full name to search for (requires company or city for disambiguation) | | `company` | string | No | Company name to help disambiguate name-based searches. Can be combined with city for better accuracy. | | `city` | string | No | City/location to help disambiguate name-based searches (e.g., San Francisco, NYC). Can be combined with company for better accuracy. | | `callback_url` | string | No | URL to receive results when processing completes | > **Required:** You must provide at least one of: email, phone, social_media_url, OR name with at least one of company or city. For best results with common names, provide both company and city. ### Request Examples **With Advanced Features:** ```json { "email": "ceo@company.com", "social_media_url": [ "https://linkedin.com/in/ceo", "https://x.com/ceo_handle", "https://instagram.com/ceo_handle" ], "callback_url": "https://yourapp.com/webhook/deep-research" } ``` **Basic Request:** ```json { "email": "ceo@company.com" } ``` **Name-Based Lookup:** ```json { "name": "John Smith", "company": "Acme Corp", "city": "San Francisco" } ``` When using name-based search, provide at least the name plus either company or city (or both) for best results. For common names, provide both company and city. ### Code Examples **cURL:** ```bash curl -X POST https://api.nyne.ai/person/deep-research \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "email": "ceo@company.com", "social_media_url": "https://linkedin.com/in/ceo", "callback_url": "https://yourapp.com/webhook/deep-research" }' ``` **Python:** ```python import requests import json import time url = "https://api.nyne.ai/person/deep-research" headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" } # Step 1: Submit deep research request data = { "email": "ceo@company.com", "social_media_url": "https://linkedin.com/in/ceo" } response = requests.post(url, headers=headers, json=data) result = response.json() request_id = result["data"]["request_id"] print(f"Request submitted: {request_id}") # Step 2: Poll for results while True: status_response = requests.get( f"{url}?request_id={request_id}", headers=headers ) status_result = status_response.json() status = status_result["data"]["status"] print(f"Status: {status}") if status == "completed": print(json.dumps(status_result, indent=2)) break elif status == "failed": print("Research failed") break time.sleep(5) ``` **JavaScript:** ```javascript const url = "https://api.nyne.ai/person/deep-research"; const headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" }; const data = { email: "ceo@company.com", social_media_url: "https://linkedin.com/in/ceo" }; // Step 1: Submit deep research request fetch(url, { method: "POST", headers: headers, body: JSON.stringify(data) }) .then(response => response.json()) .then(result => { const requestId = result.data.request_id; console.log("Request submitted:", requestId); // Step 2: Poll for results const poll = setInterval(() => { fetch(url + "?request_id=" + requestId, { headers: headers }) .then(r => r.json()) .then(status => { console.log("Status:", status.data.status); if (status.data.status === "completed") { clearInterval(poll); console.log(JSON.stringify(status, null, 2)); } else if (status.data.status === "failed") { clearInterval(poll); console.error("Research failed"); } }); }, 5000); }) .catch(error => console.error("Error:", error)); ``` **PHP:** ```php "ceo@company.com", "social_media_url" => "https://linkedin.com/in/ceo" ]; // Step 1: Submit deep research request $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); $requestId = $result["data"]["request_id"]; echo "Request submitted: " . $requestId . "\n"; // Step 2: Poll for results while (true) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url . "?request_id=" . $requestId); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $statusResponse = curl_exec($ch); $statusResult = json_decode($statusResponse, true); curl_close($ch); $status = $statusResult["data"]["status"]; echo "Status: " . $status . "\n"; if ($status === "completed") { echo json_encode($statusResult, JSON_PRETTY_PRINT) . "\n"; break; } elseif ($status === "failed") { echo "Research failed\n"; break; } sleep(5); } ?> ``` ### Response Codes | Code | Description | |------|-------------| | 202 | Research request accepted and queued for processing | | 400 | Invalid or missing request parameters | | 401 | Invalid API credentials | | 402 | Insufficient credits (requires 100 credits) | | 403 | No active subscription or product not available | | 429 | Rate limit exceeded | ### Response Example ```json { "success": true, "data": { "request_id": "a1b2c3d4e5f6...", "status": "pending", "message": "Deep research request queued for processing. Use GET with request_id to check status.", "created_on": "2024-12-24T10:30:00" }, "timestamp": "2024-12-24T10:30:00Z" } ``` --- ## GET /person/deep-research Check the status of a request. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `request_id` | string | Yes | The request ID returned from the POST request | ### Request Example ``` GET /person/deep-research?request_id=a1b2c3d4e5f6 ``` ### Response Codes | Code | Description | |------|-------------| | 200 | Status retrieved successfully (check status field for completion) | | 401 | Invalid API credentials | | 403 | Not authorized to access this resource | | 404 | Request ID not found | ### Response Example ```json { "success": true, "data": { "request_id": "a1b2c3d4e5f6...", "status": "completed", "completed": true, "result": { "enrichment": { "result": { "firstname": "John", "lastname": "Doe", "headline": "CEO at Example Corp", "careers_info": [ { "name": "Example Corp", "title": "CEO", "startDate": "2020-01", "endDate_formatted": { "is_current": true } } ], "social_profiles": { "linkedin": { "url": "https://linkedin.com/in/johndoe" }, "twitter": { "url": "https://x.com/johndoe" } } } }, "following": { "twitter": { "result": { "interactions": [ { "handle": "@techleader", "name": "Tech Leader", "follower_count": 125000, "bio": "Building the future of AI" } ] } }, "instagram": { "result": { "interactions": [ { "handle": "@sportsbrand", "name": "Sports Brand", "follower_count": 500000, "bio": "Official sports brand account" } ] } } }, "articles": { "result": { "articles": [ { "title": "Interview: CEO on the Future of AI", "url": "https://techmedia.com/interview-ceo", "source": "Tech Media", "date": "2024-11-15" } ] } }, "dossier": { "identity_snapshot": { "full_name": "John Doe", "role": "CEO", "company": "Example Corp", "location": "San Francisco, CA", "self_description": "Tech entrepreneur and AI enthusiast", "age_estimate": "38-42" }, "personal_life_hobbies": { "active_hobbies": ["Marathon running", "Rock climbing"], "entertainment_preferences": ["Sci-fi films", "Jazz music"], "personal_passions": ["Climate tech", "Youth mentoring"] }, "career_dna": { "trajectory": [ { "role": "CEO", "company": "Example Corp", "dates": "2020-present", "reasoning": "Founded company after seeing market gap" } ], "career_superpower": "Ability to bridge technical and business strategy" }, "psychographic_profile": { "archetypes": ["Visionary Builder", "Pragmatic Idealist"], "core_values": ["Innovation", "Transparency", "Impact"], "motivations": ["Building lasting technology", "Team development"] }, "social_graph_analysis": { "professional_network": "Strong VC and founder connections", "personal_interest_graph": "Active in fitness and climate communities", "inner_circle": "Close ties to 3-4 co-founders and early mentors" }, "interest_cluster_deep_dive": { "sports_fitness": { "evidence": ["@marathonworld", "@climbinglife"], "conclusion": "Dedicated endurance athlete", "conversation_angle": "Ask about recent race times" }, "causes_values": { "evidence": ["@climatefund", "@youthmentor"], "conclusion": "Passionate about climate and education", "conversation_angle": "Discuss sustainability initiatives" } }, "content_voice_analysis": { "topics": ["AI strategy", "Leadership", "Startup culture"], "tone": "Thoughtful and data-driven", "humor_style": "Dry wit, occasional self-deprecation", "strong_opinions": ["AI should augment not replace humans"] }, "key_relationships": [ { "handle": "@techmentor", "name": "Tech Mentor", "follower_count": 50000, "relationship_nature": "Early advisor and mentor", "importance": "high" } ], "conversation_starters": { "professional_hooks": ["Recent Series B funding round"], "personal_interest_hooks": ["Boston Marathon qualification"], "shared_experience_hooks": ["Both attended Stanford"], "current_events_hooks": ["Recent AI regulation debate"] }, "recommendations_how_others_see_them": { "colleague_descriptions": ["Visionary yet grounded leader"], "highlighted_qualities": ["Strategic thinking", "Empathy"], "patterns_in_praise": "Consistently praised for creating inclusive culture" }, "warnings_landmines": { "topics_to_avoid": ["Previous company acquisition controversy"], "competitors_disliked": ["RivalCorp"], "sensitive_history": ["Layoffs in 2022"], "political_hot_buttons": ["Crypto regulation"] }, "creepy_good_insights": [ { "insight": "Follows 3 adoption advocacy accounts despite no public mention of adoption", "evidence": ["@adoptionnetwork", "@fostercare", "@familyfirst"] } ], "approach_strategy": { "best_angle": "Lead with shared interest in AI ethics and climate tech", "shared_connections": ["@mutualfriend - former colleague at Tech Corp"], "resonant_topics": ["Responsible AI", "Endurance sports"], "personal_interests_to_reference": ["Marathon training", "Jazz"], "what_not_to_do": "Avoid name-dropping RivalCorp or discussing crypto" } } }, "created_on": "2024-12-24T10:30:00", "completed_on": "2024-12-24T10:35:00" }, "timestamp": "2024-12-24T10:35: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 top-level data.result object contains four sections: enrichment, following, articles, and dossier- Each section is only included when data was successfully collected for that sub-task- The dossier object contains 13 named sections (see Dossier Structure)- Field aliases for backward compatibility: content_analysis maps to content_voice_analysis, key_influencers maps to key_relationships. Old names will be removed after a 30-day sunset period- Processing stages reported in status: pending, enriching, gathering, analyzing, completed, failed --- ## Error Codes | HTTP Code | Error Code | Description | |-----------|------------|-------------| | 400 | `INVALID_PARAMETERS` | Missing or invalid request parameters | | 400 | `MISSING_PARAMETER` | Required parameter not provided | | 401 | `AUTHENTICATION_FAILED` | Invalid or missing API credentials | | 402 | `INSUFFICIENT_CREDITS` | Not enough credits (requires 100 credits) | | 403 | `NO_ACTIVE_SUBSCRIPTION` | No active subscription found | | 403 | `PRODUCT_NOT_AVAILABLE` | Deep research not available on your plan | | 403 | `ACCESS_DENIED` | Not authorized to access this resource | | 404 | `NOT_FOUND` | Request not found | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests, please slow down | | 500 | `QUEUE_ERROR` | Failed to queue request for processing | --- ## 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": "a1b2c3d4e5f6...", "status": "completed", "completed": true, "result": { "enrichment": { "..." : "..." }, "following": { "..." : "..." }, "articles": { "..." : "..." }, "dossier": { "..." : "..." } } } ``` --- ## Best Practices Prioritize inputs in this order for best match rates: 1. **Multiple Social URLs** (Best) — Pass an array of LinkedIn, Twitter/X, and Instagram URLs. Social following data is fetched in parallel with enrichment, significantly reducing total processing time.2. **Email + Social URL** (Great) — Combining an email with a social profile URL gives enrichment a strong anchor and guarantees social following data collection.3. **Email Only** (Good) — The API enriches the person first, then discovers social profiles to fetch following data. Works well but takes longer as social discovery is sequential.4. **Name + Company/City** (Moderate) — Name-based lookups require disambiguation. Provide both company and city for common names. Processing time is longer due to the initial search step. **Recommendation:** For the fastest and most comprehensive results, provide an email along with an array of social media URLs (LinkedIn, Twitter/X, Instagram). This allows all data collection to run in parallel from the start. --- ## Note for AI Agents Deep research is an asynchronous API. Submit via POST, then poll the GET endpoint every 5 seconds using the returned request_id. Typical processing time is 2–5 minutes. Alternatively, provide a callback_url to receive results automatically when processing completes. The response contains a large nested JSON object — parse the dossier sections individually rather than attempting to process the entire payload at once. --- ## Related APIs - **Person Enrichment API** — Focused enrichment data without the full dossier → `https://api.nyne.ai/documentation/person/enrichment` - **Simulation API** — Predict responses based on deep research data → `https://api.nyne.ai/documentation/person/simulation`