Personal Interests Finder API

Find out what someone is interested in by analyzing who they follow on social media. Discover their interests in sports teams, political figures, entertainment, hobbies, technology, and more.

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

How It Works

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

Output: A deep, attribution-based persona profile where every insight is tied to specific accounts they follow

Try it out: Open the API Playground

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
API Key Required

You need to log in to access your API credentials.

Log In & Get API Keys

Rate Limits

Limit Type Default Limit Description
Per Minute 30 requests Maximum requests per minute
Per Hour 500 requests Maximum requests per hour

Find Personal Interests

Submit a request to discover personal interests based on social media following patterns.

POST /person/interests

Request Parameters

Parameter Type Required Description
email string One of email, phone, or social_media_url required Email address to look up
phone string One of email, phone, or social_media_url required Phone number (US or international format)
social_media_url string One of email, phone, or social_media_url required Social media profile URL (LinkedIn, Twitter, etc.)
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",
    "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", "@a]
          }
        ]
      },
      "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
}

Ready to Get Started?

Try the API in our interactive playground or contact us for support.

Open API Playground

Email: support@nyne.com

Try EZ Tool for a no-code interface | Open Playground