# Simulation

> Predict how a person would respond to a question.

- **Endpoint:** `POST https://api.nyne.ai/person/simulation`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/simulation?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/simulation

Runs a persona simulation: predicts how a resolved person would respond to a question, with sentiment and confidence signals. Requires an identifier (`email`, `phone`, or `social_media_url`) and a `question` (max 1000 chars); optional `name`/`company`/`city` sharpen the persona. The request is queued and returns a `request_id` - poll the status endpoint about every 5 seconds or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `question` | string | **yes** | The question to simulate a response to. Required, max 1000 characters. | "How would you react to a 20% price increase?" |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. | "+1-555-123-4567" |
| `social_media_url` | string \| array | no | Profile URL, or an array of up to 3 URLs (one per platform) for faster results. At least one of email/phone/url is required. | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Optional name context. | "Jane Doe" |
| `company` | string | no | Optional employer context. | "Acme" |
| `city` | string | no | Optional location context. | "Austin" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/simulation?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Simulation | - | Minimum 10 credits required to submit; charged when processed |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `200` | Completed simulation returned inline |

## Example request

### cURL

```bash
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 '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "question": "How would you react to a 20% price increase?"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/simulation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "question": "How would you react to a 20% price increase?",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/simulation", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    question: "How would you react to a 20% price increase?",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/simulation");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "question" => "How would you react to a 20% price increase?",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "at_a_glance": {
      "sentiment": "positive",
      "short_answer": "Likely open to evaluating a cloud-native CRM if integrations and migration are strong.",
      "conviction_level": "moderate",
      "confidence": "high",
      "confidence_reason": "Strong recent social signal directly related to the question topic.",
      "key_drivers": [
        "5+ years in SaaS product leadership",
        "Recent posts about CRM limitations"
      ]
    },
    "is_sufficient_signal": true,
    "simulated_response": "We're always evaluating new tools. Our current solution has reporting gaps - show me better integrations and a faster migration path and I'd be open to a conversation."
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt