# Person Enrichment API
> Get complete contact information for any person using just an email, phone number, or social profile URL
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/enrichment`

---

## 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
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **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
> Credits are only charged when the enrichment returns data. If a person cannot be found, no credits are charged. When <code>required_fields</code> is specified, credits are also not charged if any of the required fields are missing from the result.
---

## POST /person/enrichmentEnrich person data using email, phone, or social media profile.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Email address to enrich |
| `phone` | string | No | Phone number to enrich |
| `social_media_url` | string | No | Social media profile URL (LinkedIn, Twitter, etc.) |
| `callback_url` | string | No | URL to receive results asynchronously |
| `newsfeed` | array | No | Request social media newsfeed data from specified sources |
| `ai_enhanced_search` | boolean | No | Enable AI-powered deep search to discover additional social profiles and gather more comprehensive social data (default: `false`) |
| `strict_email_check` | boolean | No | Enable strict email validation (default: `false`) |
| `lite_enrich` | boolean | No | Enable lightweight enrichment mode (default: `false`) |
| `probability_score` | boolean | No | Enable probabilistic matching algorithm (default: `false`) |
| `name` | string | No | Specify the expected person's name to guide result selection |
| `company` | string | No | Specify the company name to improve accuracy when searching by name only |
| `city` | string | No | Specify the city/location to improve accuracy when searching by name |
| `required_fields` | array | No | Specify fields that must be present in the enrichment result |

> **Required:** At least one of email, phone, social_media_url, or name must be provided.
### `ai_enhanced_search` — Advanced FeatureEnable AI-powered deep search to discover additional social profiles and gather more comprehensive social data
- **Default:** `false`

> **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` — Email Validation FeatureEnable strict email validation
- **Default:** `false`

### `lite_enrich` — Lite Enrichment FeatureEnable lightweight enrichment mode
- **Default:** `false`
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
> **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` — Probabilistic Matching FeatureEnable probabilistic matching algorithm
- **Default:** `false`
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.
### `name` — Preferred Name MatchingSpecify the expected person's name to guide result selectionWhen multiple person profiles match your input (email/phone/URL), the API normally returns the best match. By providing a name, you can influence which result is returned.
> **Note:** This parameter is optional and does not change the default behavior when omitted. Empty strings or whitespace-only values are ignored.
### `company` — Name-Based LookupSpecify the company name to improve accuracy when searching by name onlyWhen you provide only a name (without email, phone, or social_media_url), the API will search our database for the person. The company parameter helps narrow down the search results to find the correct person.- This parameter is only used when no email, phone, or social_media_url is provided- Can be combined with city for even better accuracy on common names
> **Note:** Empty strings or whitespace-only values are ignored.
### `city` — Location-Based DisambiguationSpecify the city/location to improve accuracy when searching by nameWhen searching by name, the city parameter helps disambiguate common names by filtering results to people in the specified location. LinkedIn profiles often include location information which is matched against this parameter.- Works with common city abbreviations (SF, NYC, LA, etc.)- Can be used alone with name or combined with company for even better accuracy- When both company and city are provided, both are used in search and scoring- Maximum length: 100 characters
> **Note:** Empty strings or whitespace-only values are ignored.
### `required_fields` — Conditional EnrichmentSpecify fields that must be present in the enrichment resultWhen provided, the API checks whether all specified fields are present in the enrichment result. If any required field is missing, the request returns status: failed with no data and no credits are charged. Supported values:- firstname - person's first name (standard + lite)- lastname - person's last name (standard + lite)- current_company - company name from the first organization (standard + lite)- current_title - job title from the first organization (standard + lite)- linkedin - LinkedIn profile URL (standard + lite)- email - one or more email addresses (standard only)- phone - one or more phone numbers (standard only)- twitter - Twitter/X profile URL (standard only)- instagram - Instagram profile URL (standard only)- facebook - Facebook profile URL (standard only)- github - GitHub profile URL (standard only)
> **Note:** Using a field not supported by the current enrichment mode (e.g., email with lite_enrich: true) will return a validation error. An empty array [] or omitting the parameter disables this check.
### Request Examples

**With Advanced Features:**

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

**Lite Enrichment:**

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

**With Required Fields (no charge if fields missing):**

```json
{
  "email": "john.doe@example.com",
  "required_fields": ["linkedin", "current_company"]
}
```

**Basic Request:**

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

**Name-Based Lookup:**

```json
{
  "name": "John Doe",
  "company": "Acme Corporation",
  "city": "San Francisco"
}
```
When only name is provided, the API searches for the person's LinkedIn profile and enriches from there. The company and/or city parameters help narrow down the search for common names.
### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -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"
  }'
```

**Python:**

```python
import requests
import json

url = "https://api.nyne.ai/person/enrichment"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "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))
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/person/enrichment";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "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));
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/person/enrichment";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "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

| Code | Description |
|------|-------------|
| 200 | Enrichment completed successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "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 a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The request ID returned from the enrichment call |

### Request Example

```
GET /person/enrichment?request_id=12345
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Status retrieved successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 404 | Request ID not found |

### Response Example

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

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- 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
---

## 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) |
| 400 | `invalid_required_fields` | Invalid required_fields parameter (unsupported field name or field not available in lite_enrich mode) |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 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 |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### 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
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

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

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **LinkedIn URL** (Best) — Provides the highest match rate and most accurate results. The LinkedIn profile serves as a reliable anchor for identity resolution.2. **Email Address** (Good) — Work emails typically perform better than personal emails. Provides solid match rates for most professionals.3. **Phone Number** (Lowest) — Generally has the lowest match rate. Use only when LinkedIn URL or email is unavailable.
> **Combining Inputs:** 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.
**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
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.
---

## Related APIs
- **Person Search API** — Find contacts by name, company, or role → `https://api.nyne.ai/documentation/person/search`
- **Deep Research API** — Full intelligence dossier on a person → `https://api.nyne.ai/documentation/person/deep-research`
- **Social Profiles API** — Find all social accounts for a person → `https://api.nyne.ai/documentation/person/social-profiles`