> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Intelligence

> Research any person: background reports, social profiles, articles, recent posts, interests, and who they follow.

These endpoints are async. You POST a request, get back a `request_id`, and poll `GET /v1/requests/{request_id}` until the job finishes.

<Note>
  All paid endpoints on this page accept optional `memo` (≤ 1000 chars) and
  `decisionContext` (object) body fields. Stored on the receipt for debugging
  and audit — see [Audit Trail](/sdk/audit-context).
</Note>

## Deep Research Person

`POST /v1/tools/research/person`

Get a full background report on someone -- career history, social presence, interests, and how they're connected.

<ParamField body="email" type="string" optional>
  Person's email address
</ParamField>

<ParamField body="social_media_url" type="string" optional>
  LinkedIn, Twitter, or other social profile URL
</ParamField>

<ParamField body="name" type="string" optional>
  Person's full name
</ParamField>

<ParamField body="company" type="string" optional>
  Company name (helps disambiguate)
</ParamField>

At least one of `email`, `social_media_url`, or `name` is required.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/person \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{
    "email": "satya@microsoft.com",
    "name": "Satya Nadella",
    "company": "Microsoft"
  }'
```

Takes 2-5 minutes. See [Pricing](/pricing) for costs.

### Response Structure

The result contains an `enrichment` object with contact data, plus `following`, `articles`, and `dossier` sections.

<Info>
  Emails and phone numbers are nested inside `result.enrichment`, not at the top level.
</Info>

```json theme={null}
{
  "status": "completed",
  "result": {
    "enrichment": {
      "displayname": "Satya Nadella",
      "firstname": "Satya",
      "lastname": "Nadella",
      "bio": "Chairman and CEO of Microsoft...",
      "location": "Bellevue, Washington",
      "altemails": ["satya@microsoft.com", "satya.nadella@microsoft.com"],
      "best_work_email": "satya@microsoft.com",
      "best_personal_email": null,
      "fullphone": [
        { "fullphone": "+14255551234", "type": "work" }
      ],
      "organizations": [
        {
          "name": "Microsoft",
          "title": "Chairman and CEO",
          "startDate": "2014-02",
          "endDate_formatted": { "is_current": true }
        }
      ],
      "schools_info": [
        { "name": "University of Wisconsin-Milwaukee", "degree": "MS Computer Science" }
      ],
      "social_profiles": {
        "linkedin": { "url": "https://linkedin.com/in/satyanadella", "followers": 10000000 },
        "twitter": { "url": "https://twitter.com/sataborasu", "followers": 3000000 }
      }
    },
    "following": [],
    "articles": [
      {
        "title": "Satya Nadella on the Future of AI",
        "url": "https://example.com/article",
        "source": "TechCrunch",
        "published_date": "2025-01-15"
      }
    ],
    "dossier": {}
  },
  "request_id": "req_abc123",
  "completed_at": "2025-01-15T10:30:00.000Z"
}
```

**Key fields in `result.enrichment`:**

| Field                 | Type                                           | Description                           |
| --------------------- | ---------------------------------------------- | ------------------------------------- |
| `altemails`           | `string[]`                                     | All known email addresses             |
| `best_work_email`     | `string`                                       | Best verified work email              |
| `best_personal_email` | `string`                                       | Best verified personal email          |
| `fullphone`           | `Array<{fullphone, type}>`                     | Phone numbers with type (work/mobile) |
| `organizations`       | `Array<{name, title, startDate, endDate}>`     | Work history                          |
| `schools_info`        | `Array<{name, degree, title}>`                 | Education                             |
| `social_profiles`     | `Record<platform, {url, username, followers}>` | Social accounts                       |

***

## Social Profiles

`POST /v1/tools/research/social`

Find someone's accounts across platforms -- LinkedIn, Twitter, GitHub, YouTube, and others.

<ParamField body="email" type="string" optional>
  Person's email address
</ParamField>

<ParamField body="social_media_url" type="string" optional>
  Known social profile URL to start from
</ParamField>

At least one of `email` or `social_media_url` is required.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/social \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{ "email": "satya@microsoft.com" }'
```

***

## Article Search

`POST /v1/tools/research/articles`

Find articles and interviews mentioning a person.

<ParamField body="name" type="string" required>
  Person's full name
</ParamField>

<ParamField body="company" type="string" required>
  Company name or domain
</ParamField>

<ParamField body="sort" type="string" optional default="recent">
  Sort order: `recent` or `popular`
</ParamField>

<ParamField body="limit" type="number" optional default="5">
  Max results, 1-20
</ParamField>

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/articles \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{
    "name": "Satya Nadella",
    "company": "Microsoft",
    "sort": "recent",
    "limit": 5
  }'
```

***

## Person Newsfeed

`POST /v1/tools/research/newsfeed`

Pull someone's recent social posts along with likes, replies, and shares.

<ParamField body="social_media_url" type="string" required>
  Social profile URL (Twitter, LinkedIn, etc)
</ParamField>

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/newsfeed \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{ "social_media_url": "https://twitter.com/sataborasu" }'
```

***

## Person Interests

`POST /v1/tools/research/interests`

Figure out what someone cares about -- sports, politics, tech, entertainment, and so on.

<ParamField body="email" type="string" optional>
  Person's email address
</ParamField>

<ParamField body="phone" type="string" optional>
  Person's phone number
</ParamField>

<ParamField body="social_media_url" type="string" optional>
  Social profile URL
</ParamField>

At least one of `email`, `phone`, or `social_media_url` is required.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/interests \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{ "email": "satya@microsoft.com" }'
```

***

## Person Interactions

`POST /v1/tools/research/interactions`

See who someone follows, who follows them, and who they reply to.

<ParamField body="social_media_url" type="string" required>
  Social profile or post URL (Twitter/X or Instagram)
</ParamField>

<ParamField body="type" type="string" optional default="followers,following">
  Interaction type: `replies`, `followers`, `following`, or `followers,following`
</ParamField>

<ParamField body="max_results" type="number" optional default="100">
  Max results, 1-1000
</ParamField>

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/research/interactions \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{
    "social_media_url": "https://twitter.com/sataborasu",
    "type": "followers,following",
    "max_results": 50
  }'
```

***

## SDK Usage

All six endpoints have SDK methods. The SDK signs payments and polls for results, so you just call the method and get data back.

```typescript theme={null}
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Deep research — access emails via result.enrichment
const dossier = await agent.deepResearchPerson({
  email: "satya@microsoft.com",
  name: "Satya Nadella",
  company: "Microsoft",
});

// Emails are inside result.enrichment, not at the top level
const enrichment = dossier.result.enrichment;
console.log("Work email:", enrichment.best_work_email);
console.log("All emails:", enrichment.altemails);
console.log("Phone:", enrichment.fullphone?.[0]?.fullphone);
console.log("Company:", enrichment.organizations?.[0]?.name);

// Other person intelligence endpoints
const socials = await agent.socialProfiles({ email: "satya@microsoft.com" });
const articles = await agent.articleSearch({ name: "Satya Nadella", company: "Microsoft" });
const feed = await agent.personNewsfeed({ social_media_url: "https://twitter.com/sataborasu" });
const interests = await agent.personInterests({ email: "satya@microsoft.com" });
const interactions = await agent.personInteractions({ social_media_url: "https://twitter.com/sataborasu" });
```