These endpoints are async. You POST a request, get back a request_id, and poll GET /v1/requests/{request_id} until the job finishes.
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.
LinkedIn, Twitter, or other social profile URL
Company name (helps disambiguate)
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"
}'
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"
}
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.
Known social profile URL to start from
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.
Sort order: recent or popular
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 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.
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 profile or post URL (Twitter/X or Instagram)
type
string
default:"followers,following"
Interaction type: replies, followers, following, or followers,following
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" });
