Please Log In

You need to log in to access your API credentials and start using our APIs. Start with your free trial!

Log In & Start Free Trial

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

Try the API Playground

Test the API with our interactive playground to make real requests and see live responses.

Launch Single Social Lookup Playground

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 LinkedIn profile and want to find their Twitter handle, or when you have their email and want to find their Instagram profile.

Key Features

  • Targeted Lookup: Specify exactly which social platform you want to find (e.g., "twitter", "linkedin")
  • Flexible Input: Use either an email address or a social media URL as input
  • Cross-Platform Discovery: Map from one social platform to another (e.g., LinkedIn to Twitter)
  • 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 LinkedIn profile, find the person's Twitter account
  • Given an email address, find the person's GitHub profile
  • Given a Twitter profile, find the person's LinkedIn profile

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