Skip to main content
POST
Search people (beta)
The Enrichment API is in beta. Its request and response shapes can change.
Screens people by role, place and employer. See the Search guide for the filters.

Notes

  • To authenticate, send your Tako API key in the X-API-Key header. Store it as an environment variable rather than hardcoding it.
  • The response carries its list as a card. To get the rows, pass the card’s webpage_url to Contents, or set include_contents on this request.
  • Premium fields are withheld. Export the card through Contents with premium set to true to reveal them.
  • The schema PersonListField lists the card’s fields. See What a list holds.
  • Each successful request bills one request. See Pricing.

Authorizations

X-API-Key
string
header
required

Body

application/json

A screen of employees. Contact identifiers narrow it to the people they name, beside at least one other filter.

include_contents
boolean
default:false

Inline the card's rows in the response, under card.content. Premium fields are never inlined: pass the card's webpage_url to POST /api/v1/contents with premium=true to unlock them.

max_rows
integer | null

Maximum number of rows to inline when include_contents is true. Omit it and Tako uses your account's inline row cap. Tako clamps a larger value to the card's export_pricing.max_rows_ceiling (at most 100,000). Every inlined row is billed at the POST /api/v1/contents rate. For the rest of the list, call POST /api/v1/contents with the card's webpage_url and an offset. A card export can hold up to 100,000 rows. Don't read a large export directly into a model's context: at about 15 tokens per row, 10,000 rows cost about 150,000 tokens. Write the export to a file, on disk or in memory, and have the agent parse it with code. Give the model only the rows or results it needs.

Required range: x >= 1
content_format
enum<string>
default:json_compact

Serialization for the inlined rows: 'json_compact', 'json_records', 'csv', or 'card_json'.

Available options:
csv,
json_records,
json_compact,
card_json
role
string[] | null

Title, seniority or function phrases, such as 'head of sales'.

Maximum array length: 20
company_ids
string[] | null

Employer ids from the companies endpoints.

Maximum array length: 100
company_domains
string[] | null

Employer websites.

Maximum array length: 100
person_country
string | null
person_region
string | null
person_metro
string | null
person_town
string | null

Needs person_country or person_region beside it.

company_industry
string | null

The employer's industry, by name or id, as companies/search takes it.

company_min_employees
integer | null
Required range: x >= 0
company_max_employees
integer | null
Required range: x >= 0
company_funding_stages
enum<string>[] | null

The employer's latest funding stages.

Available options:
angel,
convertible_note,
corporate_round,
debt_financing,
equity_crowdfunding,
grant,
initial_coin_offering,
non_equity_assistance,
post_ipo_debt,
post_ipo_equity,
post_ipo_secondary,
pre_seed,
private_equity,
product_crowdfunding,
secondary_market,
seed,
series_a,
series_b,
series_c,
series_d,
series_e,
series_f,
series_g,
series_h,
series_i,
series_j,
series_unknown,
undisclosed
company_startups
boolean
default:false

Employers that are startups: private companies founded in the last ten years, of a startup type, that raised a venture round or have at most 500 employees.

linkedin_urls
string[] | null

LinkedIn profile URLs.

Maximum array length: 50
emails
string[] | null
Maximum array length: 50
phones
string[] | null
Maximum array length: 50

Response

Search people (beta)

card
TakoCard · object | null
required

The list as a Tako card: embed it, inline its rows with include_contents, or pass its webpage_url to POST /api/v1/contents for every row (with an offset) and for premium fields (premium=true). PersonListField names its fields. Null when nothing matched.

total
integer
required
total_is_lower_bound
boolean
required

True when total is the count cap (500), not an exact count. POST /api/v1/contents with the card's webpage_url reads past it.

applied
string[]
required

The filters the screen ran, with their resolved values.

unresolved
string[]
required

Inputs that named nothing, as field=value.

failed
string[]

Inputs whose lookup failed or timed out, as field=value: retry them. Not a miss.

notes
string[]