# Person Ask API
> Ask natural language questions about a person and get intelligent, attributed answers
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/ask`

---

## Overview
The Person Ask API allows you to ask natural language questions about a person using their email, phone number, or social media profile. The API uses intelligent routing to determine the best data source for your question and provides attributed answers.

Questions are classified into three categories and routed to the optimal data source:

- **Personal Questions** (interests, brands, hobbies, lifestyle): Analyzes social media following patterns
- **Professional Questions** (job, company, career, education): Uses enrichment data
- **Connection Questions** (friends, followers, who interacts): Uses social interaction data
### What You Get
- **Natural Language Questions:** Ask questions in plain English about any person- **Intelligent Routing:** Automatically determines the best data source for your question- **Attributed Answers:** See which data points informed the answer (sources)- **Dynamic Fields:** Answers include structured data with field names based on your question- **Multiple Input Types:** Email, phone, or social media profile URLs- **Async Processing:** Callback support for integration workflows
## 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

- **Person Ask:** 10 credits per request
> Credits are only charged when the request is successfully processed. If no data can be found about the person, only partial credits may be charged.
---

## POST /person/askAsk a natural language question about a person.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Email address of the person |
| `phone` | string | No | Phone number of the person |
| `social_media_url` | string | No | Social media profile URL (LinkedIn, Twitter, Instagram, etc.) |
| `question` | string | Yes | The natural language question you want to ask about the person. Maximum 2000 characters. |
| `callback_url` | string | No | URL to receive results asynchronously |

> **Required:** At least one of email, phone, or social_media_url must be provided, along with the question.
### Request Examples

**With Advanced Features:**

```json
{
  "social_media_url": "https://linkedin.com/in/johndoe",
  "question": "What are their professional interests and what topics do they engage with?",
  "callback_url": "https://yourapp.com/webhook/ask"
}
```

**Basic Request:**

```json
{
  "email": "john.doe@example.com",
  "question": "What company do they work for and what is their role?"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/ask \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "question": "What company do they work for?"
  }'
```

**Python:**

```python
import requests
import json

url = "https://api.nyne.ai/person/ask"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}

data = {
    "email": "john.doe@example.com",
    "question": "What company do they work for?"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/person/ask";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    email: "john.doe@example.com",
    question: "What company do they work for?"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/person/ask";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "email" => "john.doe@example.com",
    "question" => "What company do they work for?"
];

$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);

echo json_encode($result, JSON_PRETTY_PRINT);
?>
```

### Response Codes

| Code | Description |
|------|-------------|
| 202 | Request accepted, processing started |
| 200 | Request completed (when polling status) |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123def456...",
    "status": "pending",
    "message": "Request accepted and queued for processing"
  }
}
```

---

## GET /person/ask
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/ask?request_id=abc123def456
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Status retrieved successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 404 | Request ID not found |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123def456...",
    "status": "completed",
    "result": {
      "answer": "Based on their social media following, John appears to be a fan of Nike, Adidas, and Under Armour. They follow multiple athletic brand accounts and fitness influencers.",
      "field_name": "brand_affinities",
      "field_value": ["Nike", "Adidas", "Under Armour"],
      "question_type": "personal",
      "data_source": "instagram_following",
      "sources": ["@nike", "@adidas", "@underarmour", "@nikefootball"]
    }
  }
}
```

---

## 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 answer field contains a natural language response with reasoning based on available data- The field_name is dynamically generated based on your question (e.g., brand_affinities, vacation_preferences)- The field_value array contains specific extracted values; it is only present when structured data can be extracted- The question_type classifies your question as personal, work, or social_connections- The data_source indicates which data was used: instagram_following, twitter_following, interactions, or enrichment- The sources array provides attribution showing which accounts or data points informed the answer- If the API cannot answer your question, answer will be null and a message field will explain why
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Required parameters are missing (need at least one identifier + question) |
| 400 | `invalid_question` | Question is empty, too long, or contains prohibited content |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 404 | `request_not_found` | Request ID not found (for status checks) |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 500 | `internal_error` | Internal server error |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Maximum 3 retry attempts- 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": "abc123def456...",
  "status": "completed",
  "completed": true,
  "result": {
    "answer": "Based on their social media following, John appears to be a fan of Nike and Adidas...",
    "field_name": "brand_affinities",
    "field_value": ["Nike", "Adidas"],
    "question_type": "personal",
    "data_source": "instagram_following",
    "sources": ["@nike", "@adidas"]
  }
}
```

---

## Note for AI Agents
The Person Ask API uses intelligent routing to classify questions as personal, professional, or connection-related. For best results, ask focused, specific questions rather than broad or compound queries. The question_type and data_source fields in the response indicate how your question was routed and which data was used to generate the answer.
---

## Related APIs
- **Person Enrichment API** - Get structured person data -> `https://api.nyne.ai/documentation/person/enrichment`
- **Deep Research API** - Full intelligence dossier -> `https://api.nyne.ai/documentation/person/deep-research`
- **Simulation API** - Predict how someone would respond -> `https://api.nyne.ai/documentation/person/simulation`