Person Ask API

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.

Key Features

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

Question Routing

The API intelligently routes your question to the best 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

Authentication

All API requests require authentication using your API key and secret via HTTP headers.

Header Authentication (Required)

X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Rate Limits

API usage is controlled by rate limiting mechanisms to ensure fair usage and system stability:

Per Minute: 60 requests
Per Hour: 1000 requests
Monthly: Varies by plan

Credit Usage

The Person Ask API costs 10 credits per request.

Credit Efficiency

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/ask

Ask a natural language question about a person.

POST /person/ask

Parameters

email (string, optional)
Email address of the person
Example: john.doe@example.com

phone (string, optional)
Phone number of the person
Example: +1-555-123-4567

social_media_url (string, optional)
Social media profile URL (LinkedIn, Twitter, Instagram, etc.)
Example: https://linkedin.com/in/johndoe

question (string, required)
Your Question: The natural language question you want to ask about the person
Maximum: 2000 characters
Examples:

"What company do they work for?"
"What are their interests and hobbies?"
"What is their professional background?"
"Are they active on social media?"
"What topics do they post about?"

callback_url (string, optional)
URL to receive results asynchronously
Example: https://yourapp.com/webhook/ask

Required: At least one of email, phone, or social_media_url must be provided, along with the question.

Request Example

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

Request Example with Social Media

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

Basic Ask Request

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

Basic Ask Request

import requests
import json

url = "https://api.nyne.ai/person/ask"
headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "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))

Basic Ask Request

const url = "https://api.nyne.ai/person/ask";
const headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "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));

Response Codes

202 Request accepted, processing started

200 Request completed (when polling status)

400 Invalid request parameters

401 Invalid API credentials

429 Rate limit exceeded

Initial Response (202 Accepted)

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

GET /person/ask

Check the status of an ask request and retrieve the answer when complete.

GET /person/ask?request_id=XXX

Parameters

request_id (string, required)
The request ID returned from the POST request
Example: abc123def456...

Response Example (Completed)

{ "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 Example (Processing)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "processing" } }

Response Example (Cannot Answer)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "completed", "result": { "answer": null, "message": "We could not find enough data about this person to answer your question." } } }

Response Format

Success Response

{ "success": true, "data": { "request_id": "abc123def456...", "status": "completed", "result": { "answer": "Based on their social media following, John appears to be interested in travel and outdoor activities...", "field_name": "vacation_preferences", "field_value": ["Bali", "Hawaii", "Costa Rica"], "question_type": "personal", "data_source": "instagram_following", "sources": ["@visitbali", "@gohawaii", "@visitcostarica"] } } }

Response Fields

Field	Type	Description
answer	string	Natural language answer with reasoning
field_name	string	Dynamic field name based on question (e.g., brand_affinities, vacation_preferences)
field_value	array	Array of specific values extracted from the data
question_type	string	Classification: personal, work, or social_connections
data_source	string	Which data was used: instagram_following, twitter_following, interactions, or enrichment
sources	array	Attribution showing which accounts/data points informed the answer

Error Response

{ "success": false, "error": { "code": "error_code", "message": "Error message" } }

Status Values

Status	Description
pending	Request received, waiting to be processed
processing	Request is being processed (enriching, classifying, gathering data, or answering)
completed	Request completed successfully
failed	Request failed (check error_message)

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

Callback System

When you provide a callback_url, the API will send the results to your endpoint via HTTP POST when processing completes.

Callback Request Format

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

Callback for Failed Requests

{ "request_id": "abc123def456...", "status": "failed", "completed": false, "error": "Error message describing what went wrong" }

Callback Retry Policy

Maximum 3 retry attempts
30-second timeout per request
Your endpoint should return HTTP 2xx for success

Person Ask API

API Endpoint

Overview

Key Features

Question Routing

Authentication

Rate Limits

Credit Usage

Credit Efficiency

POST /person/ask

POST /person/ask

Parameters

Request Example

Request Example with Social Media

Response Codes

Initial Response (202 Accepted)

GET /person/ask

GET /person/ask?request_id=XXX

Parameters

Response Example (Completed)

Response Example (Processing)

Response Example (Cannot Answer)

Response Format

Success Response

Response Fields

Error Response

Status Values

Error Codes

Callback System

Callback Request Format

Callback for Failed Requests

Callback Retry Policy

Related APIs

Person Enrichment API

Deep Research API

Simulation API