Skip to main content
POST
/
v1
/
tools
/
research
/
person
Person Intelligence
curl --request POST \
  --url https://win.oneshotagent.com/v1/tools/research/person \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "social_media_url": "<string>",
  "name": "<string>",
  "company": "<string>",
  "sort": "<string>",
  "limit": 123,
  "phone": "<string>",
  "type": "<string>",
  "max_results": 123
}
'
These endpoints are async. You POST a request, get back a request_id, and poll GET /v1/requests/{request_id} until the job finishes.
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.

​
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.
​
email
string
Person’s email address
​
social_media_url
string
LinkedIn, Twitter, or other social profile URL
​
name
string
Person’s full name
​
company
string
Company name (helps disambiguate)
At least one of email, social_media_url, or name is required. 
curl -X POST https://win.oneshotagent.com/v1/tools/research/person \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{
    "email": "[email protected]",
    "name": "Satya Nadella",
    "company": "Microsoft"
  }'
Takes 2-5 minutes. See Pricing for costs.

​
Response Structure

The result contains an enrichment object with contact data, plus following, articles, and dossier sections.
Emails and phone numbers are nested inside result.enrichment, not at the top level.
{
  "status": "completed",
  "result": {
    "enrichment": {
      "displayname": "Satya Nadella",
      "firstname": "Satya",
      "lastname": "Nadella",
      "bio": "Chairman and CEO of Microsoft...",
      "location": "Bellevue, Washington",
      "altemails": ["[email protected]", "[email protected]"],
      "best_work_email": "[email protected]",
      "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:
FieldTypeDescription
altemailsstring[]All known email addresses
best_work_emailstringBest verified work email
best_personal_emailstringBest verified personal email
fullphoneArray<{fullphone, type}>Phone numbers with type (work/mobile)
organizationsArray<{name, title, startDate, endDate}>Work history
schools_infoArray<{name, degree, title}>Education
social_profilesRecord<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.
​
email
string
Person’s email address
​
social_media_url
string
Known social profile URL to start from
At least one of email or social_media_url is required. 
curl -X POST https://win.oneshotagent.com/v1/tools/research/social \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{ "email": "[email protected]" }'

​
Article Search

POST /v1/tools/research/articles Find articles and interviews mentioning a person.
​
name
string
required
Person’s full name
​
company
string
required
Company name or domain
​
sort
string
default:"recent"
Sort order: recent or popular
​
limit
number
default:"5"
Max results, 1-20
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.
​
social_media_url
string
required
Social profile URL (Twitter, LinkedIn, etc)
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.
​
email
string
Person’s email address
​
phone
string
Person’s phone number
​
social_media_url
string
Social profile URL
At least one of email, phone, or social_media_url is required. 
curl -X POST https://win.oneshotagent.com/v1/tools/research/interests \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <signature>" \
  -d '{ "email": "[email protected]" }'

​
Person Interactions

POST /v1/tools/research/interactions See who someone follows, who follows them, and who they reply to.
​
social_media_url
string
required
Social profile or post URL (Twitter/X or Instagram)
​
type
string
default:"followers,following"
Interaction type: replies, followers, following, or followers,following
​
max_results
number
default:"100"
Max results, 1-1000
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. 
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

// Deep research — access emails via result.enrichment
const dossier = await agent.deepResearchPerson({
  email: "[email protected]",
  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: "[email protected]" });
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: "[email protected]" });
const interactions = await agent.personInteractions({ social_media_url: "https://twitter.com/sataborasu" });