Simulation API

Predict how a person would respond to any question by combining comprehensive intelligence data with AI-powered behavioral modeling. Get sentiment analysis, conviction levels, key drivers, and a detailed simulated response.

API Endpoint

https://api.nyne.ai/person/simulation

What's Included

  • Sentiment Analysis: Predicted stance (positive, negative, neutral, mixed, unknown)
  • Short Answer: A concise 1-2 sentence prediction of their likely response
  • Conviction Level: How strongly they would feel (strong, moderate, mild, uncertain)
  • Confidence Score: AI confidence in the prediction (high, medium, low) with reasoning
  • Key Drivers: Factors that would most influence their response
  • Simulated Response: A detailed, in-character response as the person would give it

How It Works

Input: Provide a question plus person identifiers -- email address, phone number, social media URL(s) (LinkedIn, Twitter/X, Instagram), OR a person's name with company/city for disambiguation.

Processing Pipeline:

  1. Question Analysis: AI analyzes the question to determine which data sources are most relevant
  2. Data Collection: Enrichment lookup runs question-aware prioritization
  3. Behavioral Analysis (parallel): Question-focused analysis of interaction patterns, interests, and relationships across multiple AI calls
  4. Simulation Synthesis: Final AI analysis that combines all intelligence data with the question to predict how this person would respond, including insufficient-data detection

Output: Structured simulation result with at-a-glance fields and a full simulated response, or an insufficient-data indicator when not enough signal is available.

Try the API Playground

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

Launch Simulation Playground

Prefer no-code? Try the Visual Simulation 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

Submit Simulation Request

Submit a request to simulate how a person would respond to a question.

POST /person/simulation

Request Parameters

Parameter Type Required Description
question string Yes The question to simulate a response for (max 1000 characters)
email string Conditional* Email address of the person
phone string Conditional* Phone number (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: In addition to the required question, 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 (Email Lookup)

curl -X POST "https://api.nyne.ai/person/simulation" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Would you be interested in switching to a new CRM platform?",
    "email": "ceo@company.com",
    "callback_url": "https://yourapp.com/webhook/simulation"
  }'

Example Request (Social URL)

curl -X POST "https://api.nyne.ai/person/simulation" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What do you think about remote work policies?",
    "social_media_url": "https://linkedin.com/in/ceo"
  }'

Example Request (Name-Based Search)

curl -X POST "https://api.nyne.ai/person/simulation" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do you feel about AI in the workplace?",
    "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/simulation" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Would you attend a leadership summit in Austin next quarter?",
    "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": "sim_a1b2c3d4e5f6...",
    "status": "pending",
    "message": "Simulation request queued for processing. Use GET with request_id to check status.",
    "created_on": "2025-01-15T10:30:00"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Response (200 OK - Cached)

If an identical simulation (same person + same question) was recently processed, you will receive the cached result immediately:

{
  "success": true,
  "data": {
    "request_id": "sim_a1b2c3d4e5f6...",
    "status": "completed",
    "cached": true,
    "result": { ... }
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Check Request Status

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

GET /person/simulation?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
analyzing_question Analyzing the question to determine relevant data sources
enriching Fetching enrichment data
gathering Fetching social following and article data with question-aware prioritization
simulating Running question-focused behavioral analysis and simulation synthesis
completed Simulation 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/simulation?request_id=sim_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 the simulation result with structured at-a-glance fields and a full simulated response.

Completed Response

{
  "success": true,
  "data": {
    "request_id": "sim_a1b2c3d4e5f6...",
    "status": "completed",
    "completed": true,
    "result": {
      "at_a_glance": {
        "sentiment": "positive",
        "short_answer": "Likely receptive to a new CRM if it solves their current pain points around reporting and integrations.",
        "conviction_level": "moderate",
        "confidence": "high",
        "confidence_reason": "Strong signal from career history in SaaS, social posts about CRM frustrations, and technology-forward following patterns.",
        "is_sufficient_signal": true,
        "key_drivers": [
          "History of adopting new SaaS tools early",
          "Recent social posts expressing frustration with current CRM reporting",
          "Follows multiple CRM competitors and sales tech influencers",
          "Career focus on operational efficiency and data-driven decisions"
        ]
      },
      "simulated_response": "I'd definitely be open to hearing about it. We've been frustrated with our current setup -- especially the reporting limitations and the lack of native integrations with our marketing stack. If your platform can show me better pipeline visibility and reduce the manual data entry my team deals with, I'd be interested in a demo. That said, migration cost is always a concern, so I'd want to understand the transition plan and how long until we're fully operational.",
      "raw_markdown": "## Sentiment\npositive\n\n## Short Answer\n..."
    },
    "created_on": "2025-01-15T10:30:00",
    "completed_on": "2025-01-15T10:33:00"
  },
  "timestamp": "2025-01-15T10:33:00Z"
}

Insufficient Data Response

When there is not enough intelligence data to reliably simulate a response, the API will indicate this clearly:

{
  "success": true,
  "data": {
    "request_id": "sim_x9y8z7w6...",
    "status": "completed",
    "completed": true,
    "result": {
      "at_a_glance": {
        "sentiment": "unknown",
        "short_answer": "Insufficient data to predict a reliable response.",
        "conviction_level": "uncertain",
        "confidence": "low",
        "confidence_reason": "Limited social presence and no relevant articles found.",
        "is_sufficient_signal": false,
        "key_drivers": []
      },
      "simulated_response": "There is not enough available data about this person to generate a reliable simulated response to this question.",
      "raw_markdown": "## Sentiment\nunknown\n\n## Short Answer\n..."
    },
    "created_on": "2025-01-15T11:00:00",
    "completed_on": "2025-01-15T11:02:00"
  },
  "timestamp": "2025-01-15T11:02:00Z"
}

At-a-Glance Fields

The at_a_glance object provides quick, structured insights about the simulation result.

Field Type Values Description
sentiment string positive, negative, neutral, mixed, unknown Predicted emotional stance toward the question topic
short_answer string Free text Concise 1-2 sentence summary of the predicted response
conviction_level string strong, moderate, mild, uncertain How strongly the person would hold their position
confidence string high, medium, low AI's confidence level in the prediction accuracy
confidence_reason string Free text Explanation of why the confidence level is what it is
is_sufficient_signal boolean true, false Whether enough data was available to generate a reliable simulation
key_drivers array Array of strings Key factors that would most influence the person's response

Additional Response Fields

Field Type Description
simulated_response string A detailed, in-character response written as if the person were answering the question themselves
raw_markdown string The full raw markdown output from the simulation for custom parsing

Error Codes

HTTP Status Error Code Description
400 INVALID_PARAMETERS Missing or invalid request parameters
400 MISSING_PARAMETER Required parameter not provided (e.g., missing question)
401 AUTHENTICATION_FAILED Invalid or missing API credentials
402 INSUFFICIENT_CREDITS Not enough credits (minimum 10 credits required; typical request costs ~122 credits including deep research)
403 NO_ACTIVE_SUBSCRIPTION No active subscription found
403 PRODUCT_NOT_AVAILABLE Simulation 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": "sim_a1b2c3d4e5f6...",
  "status": "completed",
  "completed": true,
  "result": {
    "at_a_glance": {
      "sentiment": "positive",
      "short_answer": "...",
      "conviction_level": "moderate",
      "confidence": "high",
      "confidence_reason": "...",
      "is_sufficient_signal": true,
      "key_drivers": [...]
    },
    "simulated_response": "...",
    "raw_markdown": "..."
  }
}

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

Deep Research API

Intelligence dossier used by simulation

Person Enrichment API

Structured person data