Personal Interests Finder API

Get the interests of a person.

API Endpoint

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

What You Can Learn

  • 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

Overview

Input: Provide an email, phone number, social media profile URL, or name

Output: Interests of the user.

Precision note: Name-only lookups can match the wrong person. Adding company and/or a LinkedIn URL improves disambiguation.

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
Please log in to access your API credentials and start using our APIs. Log In & Start Free Trial
Interactive Playground — test this API with real requests and see live responses. Launch Playground or try the no-code version

Rate Limits

Limit Type Default Limit Description
Per Minute 60 requests Maximum requests per minute
Per Hour 1000 requests Maximum requests per hour

Credit Usage

API credits are consumed for completed personal interests analyses:

  • Interest Analysis: 5 credits per completed interest profile

Credit Efficiency

Credits are only charged when the analysis returns results. If a person's social graph cannot be analyzed, no credits are charged.

Find Personal Interests

Submit a request to get the interests of a person.

POST /person/interests

Request Parameters

Parameter Type Required Description
email string One of email, phone, social_media_url, or name required Email address to look up
phone string One of email, phone, social_media_url, or name required Phone number (US or international format)
social_media_url string One of email, phone, social_media_url, or name required 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

Example Request

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"
  }'

Response (202 Accepted)

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

Check Request Status

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

GET /person/interests?request_id={request_id}

Query Parameters

Parameter Type Required Description
request_id string Yes The request ID returned from the POST request

Example Request

curl -X GET "https://api.nyne.ai/person/interests?request_id=a1b2c3d4e5f6..." \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response (Completed)

{
  "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 structure:

Success Response

{
  "success": true,
  "data": {
    // Response data varies by endpoint
  },
  "timestamp": "ISO 8601 timestamp"
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "timestamp": "ISO 8601 timestamp"
}

Response Structure

The API returns a deep, attribution-based persona profile. Every insight includes supporting_accounts that justify the inference.

Section Description Key Fields
core_profile Identity archetypes describing the person archetypes, supporting_accounts
location_intelligence Detected locations with context detected_locations (location, context, supporting_accounts)
cultural_dna Heritage and community ties heritage.primary_signals, community_ties
psychographics Psychological and value-based insights political_alignment, faith_and_values, motivations
interest_graph Detailed interest categories culinary_profile, creative_arts, sports_and_fitness, entertainment, lifestyle_and_hobbies
brand_affinities Brand preferences by category category, brands, supporting_accounts
professional_ecosystem Industry and career signals industry_signals, career_interests
social_graph_clusters Subcultures and communities cluster_label, cluster_description, supporting_accounts

Attribution: Every insight includes a supporting_accounts array listing the specific accounts that justify the inference. This makes the profile fully explainable and traceable.

Note: Only sections with detected signals are included in the response. Empty sections are omitted.

Error Codes

HTTP Status 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

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": "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

Deep Research API

Full intelligence dossier

Person Enrichment API

Complete person profile