# PumpGTM People Data API: Profiles, Email and Social Connections

Canonical URL: https://pumpgtm.com/docs/people-api

[PumpGTM](/) / [Developer docs](/docs)

# People data API

Enrich a person from a LinkedIn URL. Return professional data, an optional work email, and available social connection evidence, paid in Energy.

Updated October 4, 2026 · [View as Markdown](/markdown/pages/docs/people-api.md)

Build a person profile from one public LinkedIn URL. The same operation is available as the MCP tool [enrich_person](/docs/people-mcp). It returns data to your workflow without creating a lead or starting outreach.

## Make a request

Use your existing workspace key from MCP in [your PumpGTM workspace](https://app.pumpgtm.com/install-mcp). Keep it on your server. Your workspace must have Energy enabled and available; [billing](https://app.pumpgtm.com/billing#energy) shows your balance. If Energy is not enabled, contact [PumpGTM support](/contact).

curl https://app.pumpgtm.com/api/v1/people/enrich \
-H "Authorization: Bearer $PUMPGTM_KEY " \
-H "Content-Type: application/json" \
-d '{
"linkedinUrl": "https://www.linkedin.com/in/namanyayg",
"includeWorkEmail": true
}'

Field Type Meaning

linkedinUrl string, required Public LinkedIn person URL, at most 1,500 characters. Company URLs are rejected.

includeWorkEmail boolean, default false Also run the work-email lookup when the resolved person has a current company domain.

One person per request. The body must be valid JSON under 4 KB. Unknown fields are rejected. The credential fixes your workspace; you cannot select another customer in the body or header.

## Read the response

This is a fictional response example , not a live result or a coverage guarantee.

{
"requestId" : "example-request" ,
"status" : "matched" ,
"person" : {
"linkedinUrl" : "https://www.linkedin.com/in/arthur-dent-example" ,
"name" : "Arthur Dent" ,
"headline" : "Co-founder at Magrathea Labs" ,
"location" : "San Francisco, CA" ,
"company" : "Magrathea Labs" ,
"title" : "Co-founder" ,
"companyDomain" : "example.com" ,
"workEmail" : "arthur@example.com" ,
"emailCompanyDomainMatch" : true
},
"emailStatus" : "found" ,
"social" : {
"socialProfiles" : [{
"network" : "x" ,
"url" : "https://x.com/i/user/123" ,
"sourceUrl" : "https://x.com/i/user/123" ,
"observedAt" : "2026-10-04T12:00:00Z"
}],
"connections" : [{
"from" : "https://x.com/i/user/123" ,
"to" : "https://x.com/i/user/456" ,
"type" : "follows" ,
"sourceUrl" : "https://x.com/i/user/123/following" ,
"observedAt" : "2026-10-04T12:00:00Z"
}],
"coverage" : "Previously observed public profile links and follow relationships only. Empty arrays mean no available evidence, not no connections. Not a complete social graph."
},
"sources" : [{
"url" : "https://www.linkedin.com/in/arthur-dent-example" ,
"retrievedAt" : "2026-10-04T12:00:00Z"
}],
"billing" : { "energyCharged" : 33 , "energyHeld" : 0 , "centsPerEnergy" : 5 },
"coverage" : "Provider-reported professional data. Fields may be missing or outdated; retrievedAt is the lookup time, not the source's last update. No outreach is started."
}

status is matched when a profile is returned and any requested email was found; partial when a profile is returned without the requested email; or not_found when no exact profile match is available. A matched profile can still contain null fields.

emailStatus is not_requested , found , not_found , insufficient_identity , energy_exhausted , or unavailable . A failed email lookup can return a partial profile. Check emailCompanyDomainMatch before using an address: a returned address may belong to a different company domain. A found email is a provider result, not a delivery guarantee.

## Social connection data

socialProfiles contains accounts connected by cited public profile links. We do not match people by name alone. connections contains up to 100 previously observed, directed follow relationships associated with those accounts, with source URLs and observation times.

Coverage depends on existing permitted observations. This call does not crawl a new social graph. Empty arrays mean there is no available evidence. A follow is not a friendship, mutual connection, or endorsement. Expired and suppressed observations are excluded, and customer-private lists, messages, and targeting decisions are never returned.

## Energy and errors

One Energy is $0.05 . Each paid provider lookup reserves Energy before it runs, then settles against the provider cost recorded in the rate book. People-data lookups are priced at five times that cost, rounded up to whole Energy per lookup . For example, a lookup costing $0.0245 uses 3 Energy ($0.15). A $0.30 profile lookup uses 30 Energy ($1.50). These are pricing examples; actual provider rates and the number of lookups vary.

energyCharged is the Energy spent by this request. energyHeld is Energy reserved for calls whose final cost is still unknown. Paid attempts can cost Energy even when they return no match. Reused email results and existing social observations do not add a provider charge. An uncertain timeout retains its reservation until its cost can be reconciled.

HTTP status Error What to do

400 invalid_request Correct the JSON or LinkedIn URL.

401 unauthorized Supply a valid workspace key.

402 energy_exhausted Follow the returned refill or team-allocation guidance.

403 energy_required or tenant mismatch Enable Energy or use the correct workspace credential.

404 person_unavailable The person cannot be returned, including suppressed identities.

413 request_too_large Keep the JSON body under 4 KB.

503 people_data_unavailable The lookup could not complete. Completed work may already have used Energy.

This paid operation is not idempotent . Do not automatically retry timeouts or errors: repeated profile lookups can spend Energy again. Save the returned requestId with your result for support. Responses are private and are not cached by the API.

## Start with an existing dataset

Browse [YC founders](/yc/founders) or [early-stage investors](/yc/investors), then pass an individual public LinkedIn profile to the API. These pages contain existing curated datasets; this endpoint enriches one person and does not export a whole list or perform audience search.

For audience discovery and outreach, use the existing [workspace MCP tools](/docs/mcp). For the launch overview and interactive example, visit the [people data index](/people).

Questions or a missing endpoint: [hello@pumpgtm.com](mailto:hello@pumpgtm.com).