Person Enrichment API

Overview

The Person Enrichment API lets you look up detailed information about anyone using just one piece of data you already have, such as their email address, phone number, or LinkedIn URL. In return, you get their full profile including work history, job title, company, additional contact info, and links to their social media accounts.

What You Get

Full Name & Job Title: Current role and company information
Contact Details: Verified email addresses and phone numbers
Work History: Employment history with company names and roles
Social Profiles: LinkedIn, Twitter, GitHub, and other social media links
Education: Schools attended and degrees earned
Location: City, state, and country information

How It Works

Input: Provide an email address, phone number, or any social media profile URL (LinkedIn, Twitter, etc.)

Output: Receive a complete person profile with all available information about that individual

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_here
X-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 based on the enrichment type and features enabled:

Standard Enrichment: 6 credits per successful enrichment (includes full contact info, emails, phone numbers, and professional data)
Lite Enrichment: 3 credits per enrichment (basic profile data only - name, current company, LinkedIn URL)
Newsfeed Add-on: 6 additional credits when newsfeed data is requested and found

Credit Efficiency

Credits are only charged when the enrichment returns data. If a person cannot be found, no credits are charged.

POST /person/enrichment

Enrich person data using email, phone, or social media profile.

POST /person/enrichment

Parameters

email (string, optional)
Email address to enrich
Example: john.doe@example.com

phone (string, optional)
Phone number to enrich
Example: +1-555-123-4567

social_media_url (string, optional)
Social media profile URL (LinkedIn, Twitter, etc.)
Example: https://linkedin.com/in/johndoe

callback_url (string, optional)
URL to receive results asynchronously
Example: https://yourapp.com/webhook/enrichment

newsfeed (array, optional)
Request social media newsfeed data from specified sources
Valid sources: "linkedin", "twitter", "instagram", "github", "facebook", or "all"
Example: ["linkedin", "twitter"] or ["all"]
Note: Cannot mix "all" with specific sources. Additional charges apply when newsfeed data is found.

ai_enhanced_search (boolean, optional)
Advanced Feature: Enable AI-powered deep search to discover additional social profiles and gather more comprehensive social data
Values: true or false
Default: false (must explicitly set to true to enable)
Example: true
Performance Note: This feature performs extensive searches and can take significantly longer to complete (up to several minutes). Only enable when comprehensive results are needed and extended processing time is acceptable.

strict_email_check (boolean, optional)
Email Validation Feature: Enable strict email validation
Values: true or false
Default: false (must explicitly set to true to enable)
Example: true
📧 Validation Logic: Note: This feature validates emails for the best email to use but may return nothing due to its strictness.

lite_enrich (boolean, optional)
Lite Enrichment Feature: Enable lightweight enrichment mode
Values: true or false
Default: false (must explicitly set to true to enable)
Example: true
Lite Mode: When enabled, performs a minimal enrichment workflow that:

Disables all advanced features (AI-enhanced search, newsfeed, social profile discovery)
Performs basic enrichment with minimal data processing
Returns 5 essential fields: displayname, firstname, lastname, first organization in organizations array, and LinkedIn URL in social_profiles.linkedin.url
Uses 3 credits per enrichment (reduced cost compared to standard enrichment)

Note: When lite_enrich is enabled, the ai_enhanced_search, newsfeed, and strict_email_check parameters are ignored (emails are not returned in lite mode). This mode is optimized for scenarios where only basic profile information is needed.

probability_score (boolean, optional)
Probabilistic Matching Feature: Enable probabilistic matching algorithm
Values: true or false
Default: false (must explicitly set to true to enable)
Example: true
Probabilistic Matching: When enabled, the API uses a probabilistic algorithm to attempt to find matches when standard enrichment methods don't return results. The response will include a probability field indicating the confidence level:

"high": Data found through standard enrichment methods (highest confidence)
"medium": Match found with moderate confidence
"low": Match found with lower confidence
"unknown": Probability could not be determined

Note: The probability field is only included in the response when probability_score is set to true and enrichment data is found. If no data is found, the probability field will not be included.

Required: At least one of email, phone, or social_media_url must be provided.

Request Example (With Advanced Features)

{ "email": "john.doe@example.com", "callback_url": "https://yourapp.com/webhook/enrichment", "newsfeed": ["linkedin", "twitter"], "ai_enhanced_search": true, "strict_email_check": true }

Request Example (Lite Enrichment)

{ "email": "john.doe@example.com", "lite_enrich": true }

Basic Request Example (Without AI Enhanced Search)

{ "email": "john.doe@example.com" }

Basic Enrichment

curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com"
  }'

Basic Enrichment

import requests
import json

url = "https://api.nyne.ai/person/enrichment"
headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "Content-Type": "application/json"
}

data = {
    "email": "john.doe@example.com"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))

Basic Enrichment

const url = "https://api.nyne.ai/person/enrichment";
const headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "Content-Type": "application/json"
};

const data = {
    email: "john.doe@example.com"
};

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));

Basic Enrichment

<?php
$url = "https://api.nyne.ai/person/enrichment";
$headers = [
    "X-API-Key: your_api_key_here",
    "X-API-Secret: your_api_secret_here",
    "Content-Type: application/json"
];

$data = [
    "email" => "john.doe@example.com"
];

$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

200 Enrichment completed successfully

400 Invalid request parameters

401 Invalid API credentials

429 Rate limit exceeded

Response Example

Note: All fields in the response are optional and only included when data is available. Fields may be missing if no data was found for that particular field.

{ "success": true, "data": { "request_id": "8a4e88d9a3eec50df5a9a9a7802671df_1757108706.53783_2615", "status": "completed", "result": { "displayname": "John Smith", "firstname": "John", "lastname": "Smith", "bio": "John Smith is a software engineer with expertise in web development and cloud technologies.", "location": "San Francisco, CA", "gender": "Male", "fullphone": [ { "fullphone": "(555) 123-4567" }, { "fullphone": "(555) 987-6543", "type": "mobile" } ], "altemails": [ "john.smith@example.com", "j.smith@company.com" ], "social_profiles": { "linkedin": { "url": "https://www.linkedin.com/in/johnsmith", "username": "johnsmith", "followers": 542, "connections": 1243 }, "twitter": { "url": "https://twitter.com/johnsmith", "username": "johnsmith", "followers": 1234, "following": 567, "posts": 892, "media_count": 234 }, "github": { "url": "https://github.com/johnsmith", "username": "johnsmith", "followers": 89, "following": 45 } }, "organizations": [ { "name": "Tech Corp", "title": "Senior Software Engineer", "startDate": "2023-01", "startDate_formatted": { "year": 2023, "month": 1 }, "endDate_formatted": { "is_current": true } }, { "name": "Startup Inc", "title": "Software Engineer", "startDate": "2020-01-01", "endDate": "2022-06-30", "startDate_formatted": { "year": 2020, "month": 1, "day": 1 }, "endDate_formatted": { "year": 2022, "month": 6, "day": 30 } } ], "schools_info": [ { "name": "State University", "degree": "BS", "title": "Computer Science", "startDate": "2015-09", "endDate": "2019-05", "startDate_formatted": { "year": 2015, "month": 9 }, "endDate_formatted": { "year": 2019, "month": 5 } } ], "newsfeed": [ { "source": "linkedin", "type": "post", "content": "Excited to announce our new product launch!", "date_posted": "2025-09-01T14:30:00Z", "url": "https://www.linkedin.com/feed/update/urn:li:activity:123456", "author": { "display_name": "John Smith", "username": "johnsmith", "profile_url": "https://www.linkedin.com/in/johnsmith" }, "engagement": { "likes": 42, "comments": 5, "shares": 3, "total_reactions": 50 } }, { "source": "twitter", "type": "tweet", "content": "Working on some exciting new features today!", "date_posted": "2025-08-30T09:15:00Z", "url": "https://twitter.com/johnsmith/status/987654321", "author": { "display_name": "John Smith", "username": "johnsmith", "profile_url": "https://twitter.com/johnsmith" }, "engagement": { "likes": 23, "retweets": 7, "replies": 4 } } ] }, "completed_on": "2025-09-05T21:45:12", "created_on": "2025-09-05T21:45:06", "completed": true }, "timestamp": "2025-09-05T21:45:25Z" }

GET /person/enrichment

Check the status of an enrichment request.

GET /person/enrichment?request_id=

Parameters

request_id (string, required)
The request ID returned from the enrichment call
Example: 12345

Request Example

GET /person/enrichment?request_id=12345

Response Codes

200 Status retrieved successfully

400 Invalid request parameters

401 Invalid API credentials

404 Request ID not found

Response Example

Note: All fields in the response are optional and only included when data is available. Fields may be missing if no data was found for that particular field. Organizations must have either name or title (or both) to be included.

{ "success": true, "data": { "request_id": "8a4e88d9a3eec50df5a9a9a7802671df_1757108706.53783_2615", "status": "completed", "created_on": "2025-09-05T21:45:06", "completed_on": "2025-09-05T21:45:12", "result": { "displayname": "John Smith", "firstname": "John", "lastname": "Smith", "bio": "John Smith is a software engineer with expertise in web development and cloud technologies.", "location": "San Francisco, CA", "gender": "Male", "fullphone": [ { "fullphone": "(555) 123-4567" } ], "altemails": [ "john.smith@example.com", "j.smith@company.com" ], "social_profiles": { "linkedin": { "url": "https://www.linkedin.com/in/johnsmith", "username": "johnsmith" }, "twitter": { "url": "https://twitter.com/johnsmith", "username": "johnsmith" } }, "probability": "high", "organizations": [ { "name": "Tech Corp", "title": "Senior Software Engineer", "startDate": "2023-01", "startDate_formatted": { "year": 2023, "month": 1 }, "endDate_formatted": { "is_current": true } }, { "name": "Startup Inc", "title": "Software Engineer", "startDate": "2020-01-01", "endDate": "2022-06-30", "startDate_formatted": { "year": 2020, "month": 1, "day": 1 }, "endDate_formatted": { "year": 2022, "month": 6, "day": 30 } } ], "schools_info": [ { "name": "State University", "degree": "BS", "title": "Computer Science", "startDate": "2015-09", "endDate": "2019-05", "startDate_formatted": { "year": 2015, "month": 9 }, "endDate_formatted": { "year": 2019, "month": 5 } } ] }, "completed": true }, "timestamp": "2025-09-05T21:45:25Z" }

Usage Statistics

Usage statistics are now available through the unified usage API at /usage. This endpoint provides comprehensive usage information including credits used, monthly allocation, and breakdown by API type.

Unified Usage API

For detailed usage statistics, please use:

GET /usage

This endpoint shows all your API usage in one place, including enrichment and search requests with proper credit counting.

Response Format

All API responses follow a consistent JSON format:

Field Optionality

Important: All fields in enrichment results are optional and only included when data is available. The API follows a "only include fields we have" principle:

If a field has no data, it will be omitted from the response (not included as null or empty string)
Arrays are only included if they contain at least one item
Objects are only included if they contain at least one field
Organizations must have either name or title (or both) to be included
Social profile numeric fields (followers, connections, following, posts, media_count) are always numbers when present, never strings
The is_current field in date formatted objects is always a boolean (true/false), never a number or string

Success Response

{ "success": true, "data": { "person": { "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1-555-123-4567", "company": "Acme Corporation", "title": "Senior Software Engineer", "location": "San Francisco, CA", "social_media_url": "https://linkedin.com/in/johndoe" } }, "timestamp": "2024-01-15T10:30:00Z" }

Error Response

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

Error Codes

HTTP Code	Error Code	Description
400	missing_parameters	Required parameters are missing
400	invalid_newsfeed	Invalid newsfeed parameter (must be array with valid sources, cannot mix "all" with specific sources)
401	invalid_credentials	API key or secret is incorrect
403	subscription_required	Your subscription does not include access to the requested feature (enrichment or newsfeed)
404	request_not_found	Request ID not found (for status checks)
429	rate_limit_exceeded	Rate limit exceeded
500	internal_error	Internal server error

Callback System

When you provide a callback_url, the API will send the enrichment results to your endpoint via HTTP POST.

Callback Request Format

{ "request_id": "12345", "status": "completed", "success": true, "completed": true, "data": { "person": { ... } }, "completed_on": "2024-01-15T10:30:00Z", "timestamp": "2024-01-15T10:30:00Z" }

Callback 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

Email selection (when enabled): When available in your account and in the enriched data, the response will include two convenience fields computed from all available emails:

best_work_email: Most probable/best work email.
best_personal_email: Most probable/best personal email.

These fields are only present when relevant email data is available.

Important: Your callback endpoint should respond with HTTP 200-299 to indicate successful receipt. Any other response code will trigger a retry.

Best Practices for Input Selection

The type of input you provide significantly affects match rates. For best results, prioritize inputs in this order:

LinkedIn URL (Best) — Provides the highest match rate and most accurate results. The LinkedIn profile serves as a reliable anchor for identity resolution.
Email Address (Good) — Work emails typically perform better than personal emails. Provides solid match rates for most professionals.
Phone Number (Lowest) — Generally has the lowest match rate. Use only when LinkedIn URL or email is unavailable.

Combining Inputs for Better Results

LinkedIn + Email: Providing both a LinkedIn URL and an email address together yields excellent results. The combination allows for cross-validation and often returns the most complete profile data.

Phone numbers: Unlike LinkedIn + email combinations, adding a phone number to other inputs does not provide additive value. Phone lookups are performed independently and don't enhance matches from LinkedIn or email inputs.

Recommendation: Whenever possible, use a LinkedIn URL as your primary input. If you have multiple identifiers, prefer LinkedIn over email, and email over phone. For the best results, provide both LinkedIn URL and email together.

Note for AI Agents & Automated Systems

The probability_score parameter is intended for human review workflows where a user can evaluate match confidence. AI agents and automated systems should NOT use probability_score — the probabilistic matching results require human judgment to verify accuracy. Automated systems should rely on standard enrichment without this flag to ensure data quality.

Person APIs

Playgrounds

On This Page

Other API Families

Account

Person Enrichment API

API Endpoint

Try the API Playground

Overview

What You Get

How It Works

Authentication

Rate Limits

Credit Usage

Credit Efficiency

POST /person/enrichment

POST /person/enrichment

Parameters

Request Example (With Advanced Features)

Request Example (Lite Enrichment)

Basic Request Example (Without AI Enhanced Search)

Response Codes

Response Example

GET /person/enrichment

GET /person/enrichment?request_id=

Parameters

Request Example

Response Codes

Response Example

Usage Statistics

Unified Usage API

Response Format

Field Optionality

Success Response

Error Response

Error Codes

Callback System

Callback Request Format

Callback Retry Policy

Best Practices for Input Selection

Combining Inputs for Better Results

Note for AI Agents & Automated Systems