# Person APIs

> Resolve anyone from any identifier - then enrich, monitor, and analyze them. Search, verified contact data, social intelligence, and AI research over the same person graph.

- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns `202 Accepted` + `request_id`; poll the submit path or use a `callback_url` webhook.
- **HTML version:** https://api.nyne.ai/documentation/person

Every Person API starts from the same idea: give us whatever you have - an email address, a phone number, a social profile URL, or just a name and company - and Nyne.ai resolves it to a real person. From there each endpoint returns a different slice of that person: a full merged profile, a verified work email or mobile number, their social accounts and recent posts, or an AI-generated dossier.

All endpoints are asynchronous `POST` requests: the submit returns `202 Accepted` with a `request_id`, and you poll the same path - `GET <path>?request_id=…` - until `status` is `completed`, or supply a `callback_url` to receive the result by webhook instead.

Credits are charged only on meaningful results - an empty result never burns credits. Per-result options (verified emails, phone numbers, AI scoring) carry their own line items, listed on each endpoint's page.

## Endpoints

### Find people

Start from intent instead of an identifier - a natural-language query, keywords, or a triggering event.

- **[Person Search](https://api.nyne.ai/documentation/person/search.md)** - `POST /person/search` - Find people by natural-language query with structured filters.
- **[Discover](https://api.nyne.ai/documentation/person/discover.md)** - `POST /person/discover` - Discover matching people from keywords and location.
- **[Discovery](https://api.nyne.ai/documentation/person/discovery.md)** - `POST /person/discovery` - Discover people from the open web with natural-language queries and match conditions.
- **[Leads](https://api.nyne.ai/documentation/person/leads.md)** - `POST /person/leads` - Generate qualified lead candidates from a natural-language description.
- **[Person Events](https://api.nyne.ai/documentation/person/events.md)** - `POST /person/events` - Retrieve notable life/career events for a person.

### Enrichment & contact data

Turn an identifier into a full profile - or exactly the fields you need, like a verified email or mobile.

- **[Person Enrichment](https://api.nyne.ai/documentation/person/enrichment.md)** - `POST /person/enrichment` - Resolve a full person profile from one or more identifiers.
- **[Lookup Fields](https://api.nyne.ai/documentation/person/lookup-fields.md)** - `POST /person/lookup-fields` - Request specific fields for a person from any identifier.
- **[Email Finder](https://api.nyne.ai/documentation/person/email.md)** - `POST /person/email` - Find a verified business email for a person.
- **[Phone Finder](https://api.nyne.ai/documentation/person/phone.md)** - `POST /person/phone` - Find a phone number for a person.

### Social intelligence

Map a person's social presence: every account, recent posts, who they engage with, and whether an account is real.

- **[Social Profiles](https://api.nyne.ai/documentation/person/social-profiles.md)** - `POST /person/social-profiles` - Find all social media accounts for a person.
- **[Social Lookup](https://api.nyne.ai/documentation/person/social-lookup.md)** - `POST /person/social-lookup` - Resolve a profile on a target platform from another identifier.
- **[Single Social Lookup](https://api.nyne.ai/documentation/person/single-social-lookup.md)** - `POST /person/single-social-lookup` - Resolve a single social profile (alias of social-lookup).
- **[Social Newsfeed](https://api.nyne.ai/documentation/person/newsfeed.md)** - `POST /person/newsfeed` - Pull recent social posts from a person’s resolved profiles.
- **[Social Interactions](https://api.nyne.ai/documentation/person/interactions.md)** - `POST /person/interactions` - Surface a person’s social interactions and engagement.
- **[Competitor Engagements](https://api.nyne.ai/documentation/person/competitor-engagements.md)** - `POST /person/competitor-engagements` - Detect a person’s engagement with competitor content.
- **[Social Account Validator](https://api.nyne.ai/documentation/person/social-account-validator.md)** - `POST /person/social-account-validator` - Validate a public social profile or post and capture a screenshot.

### AI research & analysis

Let the platform read everything for you - research dossiers, interest graphs, press coverage, AI Q&A, and persona simulation.

- **[Deep Research](https://api.nyne.ai/documentation/person/deep-research.md)** - `POST /person/deep-research` - Run an in-depth autonomous research pass on a person.
- **[Personal Interests](https://api.nyne.ai/documentation/person/interests.md)** - `POST /person/interests` - Infer a person’s interests and affinities.
- **[Article Search](https://api.nyne.ai/documentation/person/articlesearch.md)** - `POST /person/articlesearch` - Find articles and press mentions for a person.
- **[Ask](https://api.nyne.ai/documentation/person/ask.md)** - `POST /person/ask` - Ask a natural-language question about a person.
- **[Simulation](https://api.nyne.ai/documentation/person/simulation.md)** - `POST /person/simulation` - Predict how a person would respond to a question.

## Worked example

The flagship endpoint, [Person Enrichment](https://api.nyne.ai/documentation/person/enrichment), shows the request/poll shape every async Person API shares. Submit any identifier, get a `request_id` back immediately, then poll the same path for the merged profile - usually ready in under a second.

### 1. Submit - `POST /person/enrichment`

```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": "jane.doe@acme.com",
    "name": "Jane Doe",
    "company": "Acme",
    "newsfeed": [
      "linkedin",
      "github"
    ],
    "ai_enhanced_search": true
  }'
```

The call returns `202 Accepted` immediately:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "queued"
}
```

### 2. Poll until completed

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

When `status` is `completed`, the same response carries the result:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "displayname": "Jane Doe",
    "firstname": "Jane",
    "lastname": "Doe",
    "headline": "VP of Product at Acme",
    "location": "San Francisco, CA",
    "best_business_email": "jane.doe@acme.com",
    "best_work_email": "jane.doe@acme.com",
    "best_personal_email": "jane@gmail.com",
    "altemails": [
      "jane.doe@acme.com",
      "jane@example.com"
    ],
    "fullphone": [
      {
        "fullphone": "+1-555-123-4567",
        "phone_type": "mobile"
      }
    ],
    "social_profiles": {
      "linkedin": {
        "url": "https://linkedin.com/in/janedoe",
        "followers": 2847
      },
      "twitter": {
        "url": "https://x.com/janedoe",
        "followers": 1234
      }
    },
    "organizations": [
      {
        "name": "Acme",
        "title": "VP of Product",
        "is_current": true
      },
      {
        "name": "StartupXYZ",
        "title": "Product Manager",
        "is_current": false
      }
    ],
    "classifications": {
      "seniority": [
        "vp"
      ],
      "job_functions": [
        "product_management"
      ],
      "employment_types": [
        "full_time"
      ]
    },
    "total_experience_years": 12
  },
  "error": null,
  "created_on": "2026-01-15T10:34:21",
  "completed_on": "2026-01-15T10:35:00"
}
```

## Authentication & credits

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

Credits are charged only on meaningful results - empty results never burn credits. Each endpoint page lists its exact credit costs.

## FAQ

### Which Person API should I start with?

Use Person Enrichment when you already have an identifier, People Search when you need to find people from criteria, and Lookup Fields when you only want selected fields such as emails, phones, work history, or social profiles.

### Can the Person APIs return contact data?

Yes. Person Enrichment, Lookup Fields, Work Email Lookup, and Phone Number Lookup can return contact fields when the data is available and permitted for your use case.

### How do async Person API requests work?

Submit a POST request and store the returned request_id, then poll the same endpoint with that request_id or provide a callback_url to receive the completed result by webhook.

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt