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
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/research/person"

payload = {
    "email": "<string>",
    "social_media_url": "<string>",
    "name": "<string>",
    "company": "<string>",
    "sort": "<string>",
    "limit": 123,
    "phone": "<string>",
    "type": "<string>",
    "max_results": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    social_media_url: '<string>',
    name: '<string>',
    company: '<string>',
    sort: '<string>',
    limit: 123,
    phone: '<string>',
    type: '<string>',
    max_results: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/research/person', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/research/person",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'social_media_url' => '<string>',
    'name' => '<string>',
    'company' => '<string>',
    'sort' => '<string>',
    'limit' => 123,
    'phone' => '<string>',
    'type' => '<string>',
    'max_results' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/v1/tools/research/person"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/research/person")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/v1/tools/research/person")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}"

response = http.request(request)
puts response.read_body

POST

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
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/research/person"

payload = {
    "email": "<string>",
    "social_media_url": "<string>",
    "name": "<string>",
    "company": "<string>",
    "sort": "<string>",
    "limit": 123,
    "phone": "<string>",
    "type": "<string>",
    "max_results": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    social_media_url: '<string>',
    name: '<string>',
    company: '<string>',
    sort: '<string>',
    limit: 123,
    phone: '<string>',
    type: '<string>',
    max_results: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/research/person', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://win.oneshotagent.com/v1/tools/research/person",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'social_media_url' => '<string>',
    'name' => '<string>',
    'company' => '<string>',
    'sort' => '<string>',
    'limit' => 123,
    'phone' => '<string>',
    'type' => '<string>',
    'max_results' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://win.oneshotagent.com/v1/tools/research/person"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://win.oneshotagent.com/v1/tools/research/person")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://win.oneshotagent.com/v1/tools/research/person")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"phone\": \"<string>\",\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}"

response = http.request(request)
puts response.read_body

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.

string

Person’s email address

LinkedIn, Twitter, or other social profile URL

string

Person’s full name

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/satyanadella", "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

POST /v1/tools/research/social Find someone’s accounts across platforms — LinkedIn, Twitter, GitHub, YouTube, and others.

string

Person’s email address

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]" }'

Response

result is keyed by platform. username and followers are present when known.

{
  "status": "completed",
  "result": {
    "linkedin": { "url": "https://www.linkedin.com/in/satyanadella", "username": "satyanadella" },
    "twitter": { "url": "https://x.com/satyanadella", "username": "satyanadella" },
    "github": { "url": "https://github.com/satyanadella" }
  },
  "request_id": "req_abc123",
  "completed_at": "2026-09-04T10:30:00.000Z"
}

Article Search

POST /v1/tools/research/articles Find articles and interviews mentioning a person.

string

required

Person’s full name

string

required

Company name or domain

string

default:"recent"

Sort order: recent or popular

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
  }'

Response

{
  "status": "completed",
  "result": [
    {
      "title": "Satya Nadella on the Future of AI",
      "url": "https://example.com/article",
      "source": "TechCrunch",
      "published_date": "2026-09-01",
      "snippet": "Nadella said the company would..."
    }
  ],
  "request_id": "req_abc123",
  "completed_at": "2026-09-04T10:30:00.000Z"
}

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/satyanadella" }'

Response

X/Twitter and LinkedIn profile URLs return the person’s recent posts with engagement counts. Each item carries platform, content, url, posted_at, likes, replies and shares.

{
  "status": "completed",
  "result": [
    {
      "platform": "twitter",
      "content": "Excited to share what the team has been building...",
      "url": "https://x.com/satyanadella/status/1234567890",
      "posted_at": "2026-09-01T14:02:11+00:00",
      "likes": 4200,
      "replies": 310,
      "shares": 560
    }
  ],
  "request_id": "req_abc123",
  "completed_at": "2026-09-04T10:30:00.000Z"
}

Person Interests

POST /v1/tools/research/interests Figure out what someone cares about — sports, politics, tech, entertainment, and so on.

string

Person’s email address

string

Person’s phone number

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 profile or post URL (Twitter/X or Instagram)

string

default:"followers,following"

Interaction type: replies, followers, following, or followers,following

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/satyanadella",
    "type": "followers,following",
    "max_results": 50
  }'

Response

result contains only the requested keys. followers and following are fullest for X/Twitter profiles; replies is available only on supported networks.

{
  "status": "completed",
  "result": {
    "followers": [
      { "platform": "twitter", "username": "someone", "display_name": "Someone", "url": "https://x.com/someone", "followers": 12000, "following": 340, "verified": false }
    ],
    "following": [
      { "platform": "twitter", "username": "another", "display_name": "Another", "url": "https://x.com/another", "followers": 98000, "following": 120, "verified": true }
    ]
  },
  "request_id": "req_abc123",
  "completed_at": "2026-09-04T10:30:00.000Z"
}

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/satyanadella" });
const interests = await agent.personInterests({ email: "[email protected]" });
const interactions = await agent.personInteractions({ social_media_url: "https://twitter.com/satyanadella" });

Overview

Email

Email Inbox

Voice

SMS

Commerce

Enrichment

Verification

Research

Local Businesses

Government

Build

Notifications

Budgets

Receipts & Analytics

Other

Compute

Browser

Person Intelligence

Deep Research Person

Response Structure

Response

Article Search

Response

Person Newsfeed

Response

Person Interests

Person Interactions

Response

SDK Usage

​Deep Research Person

​Response Structure

​Social Profiles

​Response

​Article Search

​Response

​Person Newsfeed

​Response

​Person Interests

​Person Interactions

​Response

​SDK Usage

Deep Research Person

Response Structure

Social Profiles

Response

Article Search

Response

Person Newsfeed

Response

Person Interests

Person Interactions

Response

SDK Usage