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

Single Social Lookup API

Look up a specific social media profile URL for a person using their email address or another social media URL

API Endpoint

https://api.nyne.ai/person/single-social-lookup

Overview

The Single Social Lookup API allows you to find a person's profile URL on a specific social media platform, given their email address or a profile URL from another platform. This is useful when you have a person's profile on one platform and want to find their profile on another, or when you have their email and want to find a specific social account.

Key Features

  • Targeted Lookup: Specify exactly which social platform you want to find
  • Flexible Input: Use either an email address or a social media URL as input
  • Cross-Platform Discovery: Map from one social platform to another
  • Simple Response: Returns just the URL you're looking for
  • Credit-Based: Charges only when a matching profile is found

Use Case Examples

  • Given a profile on one platform, find the person's account on another
  • Given an email address, find the person's profile on a specific platform

Authentication

All API requests require authentication using your API key and secret. You can authenticate using either HTTP headers (recommended) or query parameters.

Header Authentication (Recommended)
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

API credits are consumed for single social lookup requests:

  • Single Social Lookup: credits per successful request

Credit Efficiency

Credits are only charged when a matching profile URL is found. If no profile is found for the requested site, no credits are charged.

POST /person/single-social-lookup

Look up a specific social media profile URL for a person.

POST /person/single-social-lookup

Parameters

social_media_url (string, optional)
A social media profile URL to look up from
Example: https://linkedin.com/in/johndoe
email (string, optional)
Email address to look up from
Example: john.doe@example.com
site (string, required)
The target social media site name to find the profile for
Examples: twitter, linkedin, instagram, facebook, tiktok, pinterest, github
callback_url (string, optional)
URL to receive results asynchronously
Example: https://yourapp.com/webhook/single-social-lookup
Required: Either social_media_url or email must be provided, plus the site parameter.

Request Example

{ "social_media_url": "https://linkedin.com/in/johndoe", "site": "twitter" }

Alternative Request (with email)

{ "email": "john.doe@example.com", "site": "github" }

Response Codes

202 Request queued successfully

400 Invalid request parameters

401 Invalid API credentials

429 Rate limit exceeded

Response Example (Queued)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "queued", "message": "Single social lookup request queued. Use GET /person/single-social-lookup?request_id=... to check status." }, "timestamp": "2025-01-15T10:30:00Z" }

GET /person/single-social-lookup

Check the status of a single social lookup request.

GET /person/single-social-lookup?request_id=

Parameters

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

Request Example

GET /person/single-social-lookup?request_id=abc123def456...

Response Codes

200 Status retrieved successfully

400 Invalid request parameters

401 Invalid API credentials

404 Request ID not found

Response Example (Found)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "completed", "target_site": "twitter", "result": { "url": "https://twitter.com/johndoe", "found": true } }, "timestamp": "2025-01-15T10:30:05Z" }

Response Example (Not Found)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "completed", "target_site": "twitter", "result": { "url": null, "found": false } }, "timestamp": "2025-01-15T10:30:05Z" }

Response Example (Processing)

{ "success": true, "data": { "request_id": "abc123def456...", "status": "processing", "message": "Request is still being processed. Please check again in a few moments." }, "timestamp": "2025-01-15T10:30:02Z" }

Supported Sites

The site parameter accepts a social media site name. Here are some commonly supported sites:

Common Site Names

  • twitter - Twitter/X profiles
  • linkedin - LinkedIn profiles
  • instagram - Instagram profiles
  • facebook - Facebook profiles
  • tiktok - TikTok profiles
  • pinterest - Pinterest profiles
  • github - GitHub profiles

Additional Sites

Many additional social media sites are supported beyond the common ones listed above. The API will attempt to find profiles on any site name you specify. If you provide a full URL instead of a site name, the API will attempt to extract the site name from the URL.

Note: If the site cannot be recognized, the API will return an unrecognized_site error.

Response Format

All API responses follow a consistent JSON format:

Response Structure

The API returns a response with the result nested in a result object:

  • target_site - The site name you requested
  • result.url - The profile URL if found, or null if not found
  • result.found - Boolean indicating whether a profile was found
  • Credits are only charged when result.found is true

Success Response

{ "success": true, "data": { "request_id": "abc123...", "status": "completed", "target_site": "twitter", "result": { "url": "https://twitter.com/johndoe", "found": true } }, "timestamp": "2025-01-15T10:30:00Z" }

Error Response

{ "success": false, "error": { "code": "error_code", "message": "Error message" }, "timestamp": "2025-01-15T10:30:00Z" }

Error Codes

HTTP Code Error Code Description
400 missing_parameters Either social_media_url or email is required, plus site parameter
400 invalid_email Invalid email format
400 invalid_url Invalid social media URL format
400 unrecognized_site Could not recognize the site from the provided URL or site name
401 invalid_credentials API key or secret is incorrect
404 request_not_found Request ID not found (for status checks)
429 rate_limit_exceeded Rate limit exceeded. Wait and retry.
500 internal_error Internal server error