# Personal Interests API > Discover what someone is interested in by analyzing their social graph. Get attribution-based persona profiles with psychographics, brand affinities, and interest categories. **Base URL:** `https://api.nyne.ai` **Endpoint:** `https://api.nyne.ai/person/interests` --- ## Overview The Personal Interests Finder API analyzes who someone follows on social media and, when needed, public-web profile evidence to build a deep, attribution-based persona profile. Provide an email, phone number, social media profile URL, or name, and receive insights into their interests in sports teams, political figures, entertainment, hobbies, technology, and more. Every insight is tied to specific accounts or public signals when possible, making the profile explainable and traceable. Delivery is asynchronous: submit a request, receive a request_id, then poll or register a callback. ### What You Get - **Core Profile:** Identity archetypes with supporting account attribution- **Location Intelligence:** Detected locations with context and evidence- **Cultural DNA:** Heritage signals and community ties- **Psychographics:** Political alignment, faith/values, motivations- **Interest Graph:** Culinary, creative arts, sports, entertainment, lifestyle- **Brand Affinities:** Brand preferences by category- **Professional Ecosystem:** Industry signals and career interests ## 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 - **Interest Analysis:** 5 credits per completed interest profile (full attribution-based persona) > Credits are only charged when the analysis returns results. If a person's social graph cannot be analyzed, no credits are charged. --- ## POST /person/interestsSubmit a request to discover personal interests based on social media following patterns. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | string | No | Email address to look up | | `phone` | string | No | Phone number (US or international format) | | `social_media_url` | string | No | Social media profile URL | | `name` | string | No | Full name for public-web interest research | | `company` | string | No | Current company or workplace to disambiguate a name-based lookup | | `callback_url` | string | No | URL to receive results when processing completes | > **Required:** At least one of email, phone, social_media_url, or name must be provided. Name-only lookups can be ambiguous, so adding company and/or LinkedIn improves precision. ### Request Examples **With Advanced Features:** ```json { "email": "john.doe@example.com", "name": "John Doe", "company": "OpenAI", "callback_url": "https://yourapp.com/webhook/interests" } ``` **Basic Request:** ```json { "email": "john.doe@example.com" } ``` ### Code Examples **cURL:** ```bash curl -X POST https://api.nyne.ai/person/interests \ -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", "name": "John Doe", "company": "OpenAI", "callback_url": "https://yourapp.com/webhook/interests" }' ``` **Python:** ```python import requests import json url = "https://api.nyne.ai/person/interests" headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" } data = { "email": "john.doe@example.com", "name": "John Doe", "company": "OpenAI", "callback_url": "https://yourapp.com/webhook/interests" } 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/interests"; 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", name: "John Doe", company: "OpenAI", callback_url: "https://yourapp.com/webhook/interests" }; 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 "john.doe@example.com", "callback_url" => "https://yourapp.com/webhook/interests" ]; $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 queued for processing | | 400 | Invalid request parameters | | 401 | Invalid API credentials | | 402 | Insufficient credits | | 429 | Rate limit exceeded | ### Response Example ```json { "success": true, "data": { "request_id": "a1b2c3d4e5f6...", "status": "pending", "message": "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" } ``` --- ## GET /person/interests 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/interests?request_id=a1b2c3d4e5f6 ``` ### 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": "a1b2c3d4e5f6...", "status": "completed", "completed": true, "result": { "core_profile": { "archetypes": ["Tech Creative", "Sports Enthusiast"], "supporting_accounts": ["@techcrunch", "@espn"] }, "location_intelligence": { "detected_locations": [ { "location": "Los Angeles, CA", "context": "Local sports and food accounts", "supporting_accounts": ["@lakers", "@lafoodies"] } ] }, "psychographics": { "political_alignment": { "classification": "Moderate Conservative", "supporting_accounts": ["@wsj"] }, "motivations": [ { "insight": "Career advancement in tech", "supporting_accounts": ["@ycombinator", "@angellist"] } ] }, "interest_graph": { "sports_and_fitness": { "interests": [ {"activity": "Basketball", "supporting_accounts": ["@lakers", "@nba"]} ] }, "entertainment": { "preferences": [ {"category": "Film", "supporting_accounts": ["@a24"]} ] } }, "brand_affinities": [ { "category": "Tech", "brands": ["Apple", "Tesla"], "supporting_accounts": ["@apple", "@tesla"] } ] }, "following_count": 87, "created_on": "2024-12-24T10:30:00", "completed_on": "2024-12-24T10:31:15" }, "timestamp": "2024-12-24T10:31:20Z" } ``` --- ## Response Format All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available: - Only sections with detected signals are included in the response — empty sections are omitted- Every insight includes a supporting_accounts array listing the specific accounts that justify the inference- The profile is fully explainable and traceable through account attribution- The following_count field indicates how many accounts were analyzed- Response sections: core_profile (identity archetypes), location_intelligence (detected locations), cultural_dna (heritage and community ties), psychographics (psychological and value-based insights), interest_graph (detailed interest categories), brand_affinities (brand preferences by category), professional_ecosystem (industry and career signals), social_graph_clusters (subcultures and communities) --- ## Error Codes | HTTP Code | 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 to complete request | | 403 | `NO_ACTIVE_SUBSCRIPTION` | No active subscription found | | 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 | --- ## Callbacks When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST. ### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 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": "a1b2c3d4e5f6...", "status": "completed", "completed": true, "result": { "core_profile": { "archetypes": ["Tech Creative"], "supporting_accounts": ["@techcrunch"] }, "interest_graph": { "sports_and_fitness": { "interests": [ {"activity": "Basketball", "supporting_accounts": ["@nba"]} ] } } }, "following_count": 87 } ``` --- ## Related APIs - **Social Interactions API** — Analyze social relationships → `https://api.nyne.ai/documentation/person/interactions` - **Deep Research API** — Full intelligence dossier → `https://api.nyne.ai/documentation/person/deep-research` - **Person Enrichment API** — Complete person profile → `https://api.nyne.ai/documentation/person/enrichment`