Find contacts

POST/contacts/search

Returns contact rows for a filter, paged by cursor. Each returned contact costs one contact credit. To deliver a list, start an export instead of paging search.

Contact creditsEach returned contact costs one contact credit.

Returns contact rows for a filter, paged by cursor. Each returned contact costs one contact credit. To deliver a list, start an export instead of paging search.

Request body

filterFilterrequired

The audience to read.

Show child attributes

countriesarray of Countryoptional

Contact countries to include. Send ISO-2 codes such as us, or English names such as Germany.

exclude_countriesarray of Countryoptional

Contact countries to exclude. Send ISO-2 codes such as us, or English names such as Germany.

has_linkedinbooleanoptional

True keeps only contacts that carry a LinkedIn URL.

has_work_emailbooleanoptional

True keeps only contacts that carry a work email.

has_phonebooleanoptional

True matches contacts with a mobile or direct phone. False matches contacts without either.

include_secondary_rolesbooleanoptional

By default, filters match a person's main role. Set include_secondary_roles to true to also match their other current roles; the contact's top-level fields still show the main role. Default false.

title_querystring or array of stringoptional

Words in the current title. The match is case-insensitive and uses whole words: 'CTO' matches 'Co-founder & CTO' but not 'Director'. The words also match across punctuation: 'VP Sales' also matches 'VP, Sales' and 'VP-Sales'. Send an array to match any one of several phrases, for example ["VP Sales", "Vice President of Sales"]. A phrase that is blank after trimming answers 400 request.invalid. A leading or trailing wildcard answers 422 filter.rejected. For a substring match, use where with the contains operator on title.

functionsarray of JobFunctionoptional

Job functions to include.

operationsgeneral_managementsales_and_bizdevinformation_technologyeducationhealthcare_and_social_servicesfinance_and_accountingmanufacturing_and_productionengineeringcustomer_servicegovernment_and_public_safetymarketing_and_advertisinghuman_resourcesarts_and_creativeconstruction_and_tradeslegalsupply_chain_and_logisticsprocurementwriting_and_editorialresearch_and_scienceother

exclude_functionsarray of JobFunctionoptional

Job functions to exclude.

seniorityarray of Seniorityoptional

Seniority rungs to include.

c_levelvpdirectormanagersenior_icentryfounder_or_partnerunknown

exclude_seniorityarray of Seniorityoptional

Seniority rungs to exclude.

c_levelvpdirectormanagersenior_icentryfounder_or_partnerunknown

domainsarray of stringoptional

Current employer domains. A full URL reduces to a bare domain on input.

exclude_domainsarray of stringoptional

Current employer domains to exclude.

company_namesarray of stringoptional

Current employer names. Case-insensitive exact match after normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.

exclude_company_namesarray of stringoptional

The NOT of company_names after the same normalization. Lowercase, trim and collapse whitespace. Strip one trailing legal suffix with an optional comma, then a leading "the ". Legal suffixes: inc, inc., incorporated, llc, l.l.c., ltd, ltd., limited, corp, corp., corporation, co, co., gmbh, ag, sa, s.a., bv, b.v., plc, pty ltd, srl. An empty normalized name returns 400 request.invalid. Values are OR within this key and AND across keys.

company_sizearray of CompanySizeoptional

Company employee bands to include.

1-1011-5051-200201-500501-1K1K-5K5K-10K10K+

company_revenuearray of CompanyRevenueoptional

Company revenue ranges to include. Only companies with a known revenue range match; most small companies have none, so this key leaves them out.

0-1M1M-10M10M-50M50M-100M100M-1B1B+

industriesarray of Industryoptional

Company industries to include, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /contacts/schema/industries/values.

exclude_industriesarray of Industryoptional

Company industries to exclude, as slugs such as software_development. A label such as 'Software Development' or 'IT Services & IT Consulting' is folded to its slug. Read the values from GET /contacts/schema/industries/values.

schoolsarray of stringoptional

School names. It matches any school on the record. The match is exact on the stored value, so send the name as the record holds it.

skillsarray of stringoptional

Skill names. It matches any skill on the record. The match is exact on the stored value, which is lowercase, and the input is lowercased. Read the values from GET /contacts/schema/skills/values.

employee_count_minintegeroptional

The smallest company employee count, inclusive.

employee_count_maxintegeroptional

The largest company employee count, inclusive.

founded_year_minintegeroptional

The earliest company founding year, inclusive.

founded_year_maxintegeroptional

The latest company founding year, inclusive.

company_hq_countriesarray of Countryoptional

Company headquarters countries to include. Send ISO-2 codes such as us, or English names such as Germany.

last_round_afterYearMonthoptional

The latest financing event is after this month, exclusive.

last_round_beforeYearMonthoptional

The latest financing event is before this month, exclusive.

last_round_typesarray of FundingRoundTypeoptional

Types of the latest financing event to include.

pre_seedseedseries_aseries_bseries_c_plusprivate_equitydebtother

total_funding_minintegeroptional

The smallest total funding in US dollars, inclusive. Missing funding is null and never matches.

total_funding_maxintegeroptional

The largest total funding in US dollars, inclusive.

company_idsarray of CompanyIdoptional

Company ids (com_) of the current employer to include. Take them from POST /companies/search or POST /companies/lookup. Values are OR within this key and AND across keys. Takes up to 1,000 ids.

whereWhereNodeoptional

The condition tree. It is opened per account when the named keys cannot express the audience. The signals column is filtered here, with in or not_in.

Show child attributes

WhereGroupWhereGroupoptional

A boolean group of child nodes.

Show child attributes

andarray of WhereNodeoptional

Every child must match.

orarray of WhereNodeoptional

At least one child must match.

notWhereNodeoptional

The child must not match.

WhereLeafWhereLeafoptional

One bound condition on one column.

Show child attributes

fieldstringrequired

A contact column name, as GET /contacts/schema prints it, or signals. The name match is case-insensitive.

openumrequired

The comparison to apply. The operator list is frozen.

eqneqinnot_ingtgteltltecontainsexists

valueanyoptional

The bound value: a string, a number, a boolean, or a list of at most 50 values for in and not_in. Text columns take eq, neq, in, not_in, contains, exists, gt, gte, lt and lte with text values. role_since takes eq, neq, gt, gte, lt, lte, in, not_in and exists with YYYY-MM-DD dates. The number columns (company_employee_count, company_founded_year, company_total_funding_usd) take eq, neq, gt, gte, lt, lte, in, not_in and exists, where exists means the value is known. has_work_email and has_phone take eq and neq with true or false. The list columns (company_industries, signals, skills, languages) take in, not_in, contains, exists, eq (the list holds the value) and neq. experience, education, certifications and social take contains and exists only. exists takes no value or true; false means the column is empty. A leaf other than exists needs a value. A refused operator, value type or shape answers 422 filter.rejected and names what the column takes.

columnsarray of stringoptional

The columns to return. Every row also carries id, always first. The default is the compact set: name, title, company, company_domain, work_email, country, seniority, last_updated, mobile_phone, direct_phone, has_phone. Send ["*"] for every column.

limitintegeroptional

The page size. The default is 50 and the maximum is 500, on REST and through MCP alike. Default 50.

cursorCursoroptional

The cursor from the previous page. Omit it on the first page. Read pages until page.next_cursor is null.

max_rows_per_companyintegeroptional

The most contacts to return from one company. On search the cap holds inside one page, so next_cursor is null when it is set; use start_export for the full capped list. On export the file can hold fewer rows than rows_to_export, and only exported rows are charged.

exclude_idsarray of PersonIdoptional

Person ids to leave out of count, search and export. Unknown ids have no effect. Takes up to 1,000 ids.

Response

The fields inside data. The contact rows of this page, in the default sort order. The field names and their types live at GET /contacts/schema.

idPersonIdoptional

Our person id. Store this one.

namestring or nulloptional

The full name of the person.

first_namestring or nulloptional

The given name.

last_namestring or nulloptional

The family name.

headlinestring or nulloptional

The short self description on the public profile.

biostring or nulloptional

The long self description on the public profile.

locationstring or nulloptional

The location as one display string.

citystring or nulloptional

The city of the person.

regionstring or nulloptional

The state, province or region.

countryCountry or nulloptional

The country as a lowercase ISO-2 slug.

linkedinstring or nulloptional

The full LinkedIn profile URL, https://www.linkedin.com/in/<slug>. It is lowercased and carries no query string.

work_emailstring or nulloptional

The work email, lowercased.

has_work_emailbooleanoptional

True when a work email is present.

email_statusEmailStatus (slug)optional

The work email status comes from our data source; verified_at is the month the source last verified the address.

unknownvalidinvalidcatch_all

verified_atstring or nulloptional

The month the source last verified the address, or null.

titlestring or nulloptional

The current job title.

functionJobFunction (slug) or nulloptional

The job function of the current role.

senioritySeniority (slug) or nulloptional

The seniority rung of the current role.

company_idCompanyId or nulloptional

Our id for the current employer.

companystring or nulloptional

The name of the current employer.

company_domainstring or nulloptional

The bare domain of the current employer.

company_sizeCompanySize (slug) or nulloptional

The employee band of the current employer.

company_revenueCompanyRevenue (slug) or nulloptional

The yearly revenue range of the current employer. Null when the range is not known, which is the case for most small companies.

company_industriesarray of Industryoptional

The industries of the current employer.

company_locationstring or nulloptional

The location of the current employer as one display string.

company_linkedinstring or nulloptional

The LinkedIn URL of the current employer.

experiencearray of objectoptional

The person's current roles only, main role first. The source has no past roles.

Show child attributes

is_mainbooleanoptional

True for the person's main role, the one the top-level fields show.

descriptionstring or nulloptional

What the role involves, as the record states it, cut to 1,000 characters.

titlestring or nulloptional

The job title in that role.

seniorityJobSeniority (slug) or nulloptional

The seniority rung of that role.

job_typestring or nulloptional

How the role was held, for example full time, part time, contract or internship.

company_idCompanyId or nulloptional

Our company id when the company is in our table, else null; fetch the company row for size, industries and funding.

companystring or nulloptional

The employer name.

domainstring or nulloptional

The bare domain of the employer.

startYearMonth or nulloptional

The month the role started.

endYearMonth or nulloptional

Always null: the source has no ended roles.

currentbooleanoptional

Always true: every role in experience is current.

skillsarray of stringoptional

The skills the record attaches to that role.

educationarray of objectoptional

The education history, newest first.

Show child attributes

schoolstring or nulloptional

The school name.

school_domainstring or nulloptional

The bare domain of the school.

school_linkedinstring or nulloptional

The full LinkedIn URL of the school, https://www.linkedin.com/school/<slug>, or the company URL when the record carries that one.

degreestring or nulloptional

The degree earned.

fieldstring or nulloptional

The field of study.

startstring or nulloptional

When the study started, YYYY-MM or a year.

endstring or nulloptional

When the study ended, YYYY-MM or a year.

activitiesstring or nulloptional

The clubs, societies and activities the record lists.

descriptionstring or nulloptional

The free text the record carries about the study.

certificationsarray of objectoptional

The certifications on the record.

Show child attributes

namestring or nulloptional

The certification name.

issuerstring or nulloptional

The body that issued it.

yearinteger or nulloptional

The year it was issued.

socialarray of objectoptional

The other public profiles on the record.

Show child attributes

networkstring or nulloptional

The network the profile sits on, for example twitter or github.

urlstring or nulloptional

The full profile URL.

usernamestring or nulloptional

The username on that network.

followersinteger or nulloptional

The follower count, or null when the record carries none.

connectionsinteger or nulloptional

The connection count, or null when the record carries none.

signalsarray of Signaloptional

The signals on the contact. Filter them with in or not_in on signals inside where.

one_year_at_companynew_in_role_90drecent_job_changefounderat_public_company

skillsarray of stringoptional

The skills on the record.

languagesarray of stringoptional

The languages on the record.

role_sinceCalendarDate or nulloptional

The day the current role started.

last_updatedYearMonth or nulloptional

The month any field on the record changed.

last_refreshedYearMonth or nulloptional

The month we re-checked the record, even when nothing changed. Null until a refresh exists: nothing re-checks records yet.

mobile_phonestring or nulloptional

The mobile phone in E.164 form, or null.

direct_phonestring or nulloptional

The direct work line in E.164 form, or null.

has_phonebooleanoptional

True when a mobile or direct phone is present.

job_descriptionstring or nulloptional

The description of the current role from the public profile.

Failures

Status	Meaning
400	The request shape, a filter key, a value, a cursor or the enrichment mode was rejected.
401	The credential is missing, unknown or revoked.
402	The daily or the monthly contact credit cap is spent, or the free plan's lifetime pool is.
422	The filter was rejected before it ran: more than 32 predicates, deeper than 4, more than 25 leaves, more than 1,000 domains or company names, more than 50 values in another list, a leading wildcard in a where leaf, a leading or trailing wildcard in title_query, an operator, value type or shape the column does not take, a leaf other than exists with no value, or an empty `and` or `or` group.
429	The key passed 300 requests a minute or 2 concurrent requests.
503	The data is unavailable for a short time.
504	The query passed its time budget and was stopped.

Docs for agents: llms.txt