Deep Research API

Generate a person intelligence report by combining multiple data sources with AI-powered analysis. Get enrichment data, social following patterns, article mentions, and an LLM-generated dossier in a single API call.

API Endpoint

https://api.nyne.ai/person/deep-research

What's Included

  • 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 intelligence report

How It Works

Input: Provide an email address, phone number, social media URL(s) (LinkedIn, Twitter/X, Instagram), OR a person's name with company/city for disambiguation. Pass multiple social URLs as an array for faster results.

Processing Pipeline:

  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

Output: Complete research package with enrichment data, social analysis, articles, and an AI-generated 13-section dossier.

Try the API Playground

Test the API with our interactive playground to make real requests and see live responses.

Launch Deep Research Playground

Prefer no-code? Try the Visual Deep Research Tool - same results, simpler interface.

Authentication

All API requests require authentication using your API key and secret in the request headers:

X-API-Key: your_api_key
X-API-Secret: your_api_secret
API Key Required

You need to log in to access your API credentials.

Log In & Get API Keys

Rate Limits

Limit Type Default Limit Description
Per Minute 10 requests Maximum requests per minute
Per Hour 100 requests Maximum requests per hour

Credit Cost: 100 credits per request

Submit Deep Research Request

Submit a request to generate a deep research report on a person.

POST /person/deep-research

Request Parameters

Parameter Type Required Description
email string Conditional* Email address to research
phone string Conditional* Phone number to research (E.164 format preferred, e.g., +15551234567)
social_media_url string | string[] Conditional* 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 Conditional* Full name to search for (requires company or city)
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

*Conditional: 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.

Example Request (Direct Lookup)

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

Example Request (Name-Based Search)

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 '{
    "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.

Example Request (Multiple Social URLs)

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 '{
    "social_media_url": [
      "https://linkedin.com/in/ceo",
      "https://x.com/ceo_handle"
    ]
  }'

When multiple URLs are provided, social following data is fetched immediately in parallel with enrichment, reducing processing time.

Response (202 Accepted)

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

Check Request Status

Check the status of a pending deep research request and retrieve results when complete.

GET /person/deep-research?request_id={request_id}

Query Parameters

Parameter Type Required Description
request_id string Yes The request ID returned from the POST request

Processing Stages

Status Description
pending Request queued for processing
enriching Fetching enrichment data
gathering Fetching social following and article data
analyzing Running batch analysis, cluster analysis, and final synthesis (up to 13 AI calls)
completed Research complete, results available
failed Processing failed
Polling Recommendations:
  • Recommended poll interval: 5 seconds
  • Typical processing time: 2-5 minutes
  • Maximum wait time: 10 minutes before considering timeout

Example Request

curl -X GET "https://api.nyne.ai/person/deep-research?request_id=a1b2c3d4e5f6..." \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response Format

When the request is completed, the response includes full enrichment data, social following lists, articles, and the AI-generated dossier.

Completed Response

{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6...",
    "status": "completed",
    "completed": true,
    "result": {
      "enrichment": {
        "result": {
          "firstname": "John",
          "lastname": "Doe",
          "headline": "CEO at Example Corp",
          "careers_info": [...],
          "social_profiles": {...}
        }
      },
      "following": {
        "twitter": {
          "result": {
            "interactions": [...]
          }
        },
        "instagram": {
          "result": {
            "interactions": [...]
          }
        }
      },
      "articles": {
        "result": {
          "articles": [...]
        }
      },
      "dossier": {
        "identity_snapshot": {...},
        "personal_life_hobbies": {...},
        "career_dna": {...},
        "psychographic_profile": {...},
        "social_graph_analysis": {...},
        "interest_cluster_deep_dive": {...},
        "content_voice_analysis": {...},
        "content_analysis": {...},
        "key_relationships": [...],
        "key_influencers": [...],
        "conversation_starters": {...},
        "recommendations_how_others_see_them": {...},
        "warnings_landmines": {...},
        "creepy_good_insights": [...],
        "approach_strategy": {...}
      }
    },
    "created_on": "2024-12-24T10:30:00",
    "completed_on": "2024-12-24T10:35:00"
  },
  "timestamp": "2024-12-24T10:35:00Z"
}

Dossier Structure

The AI-generated dossier provides deep intelligence with evidence-based insights.

# Section Type Description
1 identity_snapshot object Full name, role, company, location, emails, social profiles, self-description, age estimate
2 personal_life_hobbies object Active hobbies/sports, entertainment/culture preferences, personal passions, life outside work, personality quirks
3 career_dna object Career trajectory with roles, companies, dates, reasoning for each move, career superpower
4 psychographic_profile object Archetypes, core values, motivations, political leanings, cluster analysis of following
5 social_graph_analysis object Professional network summary, personal interest graph, inner circle overview
6 interest_cluster_deep_dive object 9 sub-clusters (sports, music, food, causes, intellectual, tech, geographic, personal network, unexpected) each with @handle evidence, conclusions, and conversation angles
7 content_voice_analysis object Topics, tone, humor style, recent wins, frustrations, strong opinions, notable quotes
8 key_relationships array[25] Top 25 relationships with handle, name, follower count, relationship nature, importance
9 conversation_starters object 30+ starters in 4 categories: professional hooks, personal interest hooks, shared experience hooks, current events hooks
10 recommendations_how_others_see_them object Colleague descriptions, highlighted qualities, patterns in praise from recommendations
11 warnings_landmines object Topics to avoid, competitors they dislike, sensitive career history, political hot buttons
12 creepy_good_insights array Non-obvious insights with supporting evidence
13 approach_strategy object Best angle, shared connections, resonant topics, personal interests to reference, what not to do
Field Aliases (Backward Compatibility):

The following fields are returned under both their old and new names. The old names will be removed after a 30-day sunset period:

  • content_analysis → content_voice_analysis
  • key_influencers → key_relationships

Error Codes

HTTP Status 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

Callback Notifications

When you provide a callback_url, we'll send a POST request to that URL when processing completes:

POST your_callback_url
Content-Type: application/json

{
  "request_id": "a1b2c3d4e5f6...",
  "status": "completed",
  "completed": true,
  "result": {
    "enrichment": {...},
    "following": {...},
    "articles": {...},
    "dossier": {...}
  }
}

Ready to Get Started?

Try the API in our interactive playground or contact us for support.

Open API Playground

Email: support@nyne.ai

Try Visual Tool for a no-code interface | Open Playground

Related APIs

Person Enrichment API

Focused enrichment data

Simulation API

Predict responses based on research