Person Intelligence

curl --request POST \
  --url https://win.oneshotagent.com/v1/tools/lookup/person-dossier \
  --header 'Content-Type: application/json' \
  --data '
{
  "include_phone": true,
  "social_media_url": "<string>",
  "name": "<string>",
  "company": "<string>",
  "sort": "<string>",
  "limit": 123,
  "type": "<string>",
  "max_results": 123
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/lookup/person-dossier"

payload = {
    "include_phone": True,
    "social_media_url": "<string>",
    "name": "<string>",
    "company": "<string>",
    "sort": "<string>",
    "limit": 123,
    "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({
    include_phone: true,
    social_media_url: '<string>',
    name: '<string>',
    company: '<string>',
    sort: '<string>',
    limit: 123,
    type: '<string>',
    max_results: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/lookup/person-dossier', 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/lookup/person-dossier",
  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([
    'include_phone' => true,
    'social_media_url' => '<string>',
    'name' => '<string>',
    'company' => '<string>',
    'sort' => '<string>',
    'limit' => 123,
    '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/lookup/person-dossier"

	payload := strings.NewReader("{\n  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\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/lookup/person-dossier")
  .header("Content-Type", "application/json")
  .body("{\n  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}"

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

POST

tools

lookup

person-dossier

Person Intelligence

curl --request POST \
  --url https://win.oneshotagent.com/v1/tools/lookup/person-dossier \
  --header 'Content-Type: application/json' \
  --data '
{
  "include_phone": true,
  "social_media_url": "<string>",
  "name": "<string>",
  "company": "<string>",
  "sort": "<string>",
  "limit": 123,
  "type": "<string>",
  "max_results": 123
}
'

import requests

url = "https://win.oneshotagent.com/v1/tools/lookup/person-dossier"

payload = {
    "include_phone": True,
    "social_media_url": "<string>",
    "name": "<string>",
    "company": "<string>",
    "sort": "<string>",
    "limit": 123,
    "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({
    include_phone: true,
    social_media_url: '<string>',
    name: '<string>',
    company: '<string>',
    sort: '<string>',
    limit: 123,
    type: '<string>',
    max_results: 123
  })
};

fetch('https://win.oneshotagent.com/v1/tools/lookup/person-dossier', 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/lookup/person-dossier",
  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([
    'include_phone' => true,
    'social_media_url' => '<string>',
    'name' => '<string>',
    'company' => '<string>',
    'sort' => '<string>',
    'limit' => 123,
    '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/lookup/person-dossier"

	payload := strings.NewReader("{\n  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\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/lookup/person-dossier")
  .header("Content-Type", "application/json")
  .body("{\n  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"include_phone\": true,\n  \"social_media_url\": \"<string>\",\n  \"name\": \"<string>\",\n  \"company\": \"<string>\",\n  \"sort\": \"<string>\",\n  \"limit\": 123,\n  \"type\": \"<string>\",\n  \"max_results\": 123\n}"

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

All six endpoints are async: POST, get a request_id, poll GET /v1/requests/{request_id}.

Optional memo (≤ 1000 chars) and decisionContext (object) body fields are stored on the receipt. See Audit Trail.

Person Dossier

POST /v1/tools/lookup/person-dossier

boolean

default:"false"

Buy a phone lookup for one person; see Pricing. No hit guaranteed.

Same as profile_url (older name): a LinkedIn, Twitter or other social profile URL

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-dossier \
  -H "Content-Type: application/json" \
  -H "X-Quote-ID: <context.quote_id from the first unpaid POST>" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "email": "[email protected]",
    "name": "Satya Nadella",
    "company": "Microsoft"
  }'

Takes 2-5 minutes. See Pricing.

Response Structure

Each section has state (found, none, or unavailable: lookup failed or identifiers missing) and data. An optional section failing does not fail the dossier. A missing profile fails the job; the call is refunded in full.

Section	Data
`profile`	The Person Profile fields, including `social_accounts`
`social_accounts`	Accounts in the profile record plus the caller URL: `platform`, `url`, `handle` (nullable). A caller URL on an unrecognised network keeps its site name as `platform` (`facebook.com/jane` → `facebook`) with a null `handle`
`articles`	Person Articles results: `title`, `url`, `source` (publication), `published_date`, `snippet`
`posts`	Up to ten Person Posts items
`summary`	A string written from the four sections, with citations; one line when only the profile was found

The dossier does not buy a username search; use Person Social Accounts for that. If the summary cannot be written, summary reads “Summary unavailable.”

{
  "status": "completed",
  "result": {
    "profile": {"state": "found", "data": {
      "full_name": "Jane Doe", "first_name": "Jane", "last_name": "Doe",
      "title": "Engineer", "company": "Example", "company_domain": "example.com",
      "linkedin_url": null, "location": null, "email": "[email protected]",
      "phone": null, "summary": null, "social_accounts": [], "altemails": ["[email protected]"]
    }},
    "social_accounts": {"state": "none", "data": []},
    "articles": {"state": "none", "data": []},
    "posts": {"state": "unavailable", "data": []},
    "summary": "Only the profile was found; no additional account, article or post content was found."
  },
  "request_id": "req_abc123",
  "completed_at": "2026-10-14T10:00:00Z"
}

POST /v1/tools/lookup/person-social-accounts Finds a person’s accounts: LinkedIn, Twitter, GitHub, YouTube and others. Start from a name and company, an email, a phone or one account you already know.

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-social-accounts \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -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"
}

Person Articles

POST /v1/tools/lookup/person-articles Articles and interviews that mention a person.

string

required

Person’s full name

string

required

Company name or domain

string

default:"recent"

recent or popular

number

default:"5"

Max results, 1-20

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-articles \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -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 Posts

POST /v1/tools/lookup/person-posts A person’s recent social posts with likes, replies and shares. Start from a profile URL, or from a name and company: the person’s LinkedIn or X profile is found first.

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-posts \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{ "social_media_url": "https://twitter.com/satyanadella" }'

Response

X/Twitter and LinkedIn profile URLs are supported. 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/lookup/person-interests Returns a person’s interests.

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-interests \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{ "email": "[email protected]" }'

Person Followers

POST /v1/tools/lookup/person-followers A person’s followers and the accounts they follow. Start from an X profile or post URL, or from a name and company: the person’s X profile is found first.

string

default:"followers,following"

replies, followers, following or followers,following

number

default:"100"

Max results, 1-1000

curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-followers \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "social_media_url": "https://twitter.com/satyanadella",
    "type": "followers,following",
    "max_results": 50
  }'

Response

result holds only the requested keys. followers and following are most complete on X/Twitter; replies 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

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

// Person dossier — access emails via result.profile.data
const dossier = await agent.personDossier({
  email: "[email protected]",
  name: "Satya Nadella",
  company: "Microsoft",
  timeout: 300, // seconds; the dossier takes a few minutes
});

// Contact data is in the profile section
const enrichment = dossier.result.profile.data;
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.company);

// Other person intelligence endpoints
const socials = await agent.personSocialAccounts({ email: "[email protected]" });
const articles = await agent.personArticles({ name: "Satya Nadella", company: "Microsoft" });
const feed = await agent.personPosts({ name: "Satya Nadella", company: "Microsoft" });
const interests = await agent.personInterests({ email: "[email protected]" });
const interactions = await agent.personFollowers({ profile_url: "https://x.com/satyanadella" });

Overview

Compute

Data

Monitoring

Research & Enrich

Messaging

Web & Browser

Build

Commerce

Account & billing

Other

Person Intelligence

Person Dossier

Response Structure

Response

Person Articles

Response

Person Posts

Response

Person Interests

Person Followers

Response

SDK Usage

​Person Dossier

​Response Structure

​Person Social Accounts

​Response

​Person Articles

​Response

​Person Posts

​Response

​Person Interests

​Person Followers

​Response

​SDK Usage

Person Dossier

Response Structure

Person Social Accounts

Response

Person Articles

Response

Person Posts

Response

Person Interests

Person Followers

Response

SDK Usage