Skip to main content
Access: All users. See Access control.

search_contacts

Search the Seamless.AI database for contacts matching filters like company, title, seniority, and location. At least one filter (or savedSearchId) is required; a call with none is rejected rather than returning an empty page. Returns a paginated table of matching contacts. Costs 1 credit per 50 results returned, rounded up; a page is trimmed to the rows the remaining credits cover. For contacts you have already saved, use get_my_contacts instead.

Arguments

string
Opaque token from pagination.nextCursor
integer
Page size (default 50). Must match the first page’s when cursor is set
integer | string
Run the filters held by a saved search, found via list_saved_searches. Cannot be combined with other filters.
string[]
Filter by company names.Up to 100 items.
string[]
Deprecated alias for companyName. Prefer companyName.Up to 100 items.
string
default:"default"
Company name match type.One of: default, related, exact.
string[]
Filter by company domains.Up to 100 items.
string[]
Filter by state or region, named or abbreviated (e.g. [“Texas”, “CA”, “Ontario”]). Prefix a value with ”-” to exclude it. Which entity this applies to is controlled by locationType.Up to 10 items.
string[]
Filter by country (e.g. [“United States”]). Prefix a value with ”-” to exclude it. Which entity this applies to is controlled by locationType. Combined with locations.Up to 10 items.
string[]
Filter by zip code. Prefix a value with ”-” to exclude it. Which entity this applies to is controlled by locationType.Up to 10 items.
string[]
Filter by free-form location tags — city, state/region, or country, and the only way to filter by city (e.g. [“Austin, Texas”, “Ontario, Canada”]). Prefix a value with ”-” to exclude it. Which entity this applies to is controlled by locationType. Combined with contactCountry.Up to 10 items.
string | number
Widen locations and contactCountry to everything within a radius of each value. The value is the radius in miles: 25, 50, 100, or 250. Only geocodable values (cities, zip codes) get a radius; use zipCodesRadius for contactZipCode.One of: 25, 50, 100, 250.
string | number
Widen contactZipCode to everything within a radius of each zip code. The value is the radius in miles: 25, 50, 100, or 250.One of: 25, 50, 100, 250.
string[]
Filter by timezone (e.g. [“Eastern (EST)”, “Pacific (PST)”]). Which entity this applies to is controlled by timezoneType.One of: Eastern (EST), Central (CST), Mountain (MST), Pacific (PST), Alaska (AKST), Hawaii (HST), New Zealand (NST), Solomon (SST), Australia Eastern (AET), Australia Central (ACT), Japan (JST), China Taiwan (CTT), Vietnam (VST), Bangladesh (BST), India (IST), Indiana Eastern (IET), Pakistan Lahore (PLT), Near East (NET), Middle East (MET), Eastern African (EAT), (Arabic) Egypt (ART), Eastern European (EET), European Central (ECT), Greenwich Mean (GMT), Central African (CAT), Argentina (AGT), Brazil Eastern (BET), Canada Newfoundland (CNT), Puerto Rico and US Virgin Islands (PRT), Midway Islands (MIT).Up to 10 items.
string
default:"bothOR"
Determines which entity the timezones filter applies to, using the same values as locationType. Ignored unless timezones is set.One of: bothOR, bothAND, company, contact.
string
default:"bothOR"
Determines which entity the location filters apply to. Use “company” when the location modifies a company noun or appears alongside company attributes (e.g. “SaaS companies in Texas”, “companies headquartered in New York”, “startups in California”). Use “contact” when explicit personal-location language like “based in”, “located in”, “live in”, or “residing in” is used with a person noun (e.g. “reps based in Chicago, Illinois”, “account executives located in Florida”). Use “bothOR” (default) when the query is ambiguous — a role plus “in [location]” with no company context or personal-location verb (e.g. “VPs of Marketing in Texas”, “engineers in Seattle, Washington”).One of: bothOR, bothAND, company, contact.
string[]
Filter by department.One of: Sales, Marketing, Human Resources, IT, Engineering, Operations, Finance, Support, Legal, Project Management, Other.Up to 5 items.
string[]
Filter by industry (e.g. [“Financial Services”, “-Staffing and Recruiting”]). Prefix a value with ”-” to exclude it.Up to 5 items.
(string | integer)[]
Filter by SIC code, independently of industry (e.g. [“7372”, “-5734”]). Prefix a value with ”-” to exclude it.Up to 5 items.
(string | integer)[]
Filter by NAICS code, independently of industry (e.g. [“511210”, “-561310”]). Prefix a value with ”-” to exclude it. Matched against the company’s own naicsCode; a company that has no naicsCode also matches when its SIC code maps to a requested code.Up to 5 items.
string[]
Filter by contact full name.Up to 10 items.
string[]
Deprecated alias for fullName. Prefer fullName.Up to 10 items.
string[]
Deprecated alias for fullName. Prefer fullName.Up to 10 items.
string[]
Filter by job title.Up to 10 items.
string[]
Deprecated alias for jobTitle. Prefer jobTitle.Up to 10 items.
boolean
default:"false"
When true, jobTitle must match exactly. Defaults to false (relevance matching, so “VP of Sales” also matches “Vice President, Sales”).
string[]
Filter by seniority level.One of: C-Level, VP, Director, Manager, Senior, Mid-Level, Entry Level, Other.Up to 5 items.
string[]
Filter by years since company was founded.One of: Less than 1 Year, Last 1-3 Years, Last 4-10 Years, 10+ Years.Up to 4 items.
string[]
Filter by company employee count range. Provide multiple ranges to cover a broader span (e.g. [“11 - 50”, “51 - 200”] for 11-200 employees). Values must match exactly.One of: 0 - 1 (Self-employed), Self-employed, 2 - 10, 2 - 10 employees, 11 - 50, 11 - 50 employees, 51 - 200, 51 - 200 employees, 201 - 500, 201 - 500 employees, 501 - 1,000, 501 - 1,000 employees, 1,001 - 5,000, 1,001 - 5,000 employees, 5,001 - 10,000, 5,001 - 10,000 employees, 10,001+, 10,001+ employees.Up to 10 items.
string[]
Deprecated alias for companySize. Prefer companySize.One of: 0 - 1 (Self-employed), Self-employed, 2 - 10, 2 - 10 employees, 11 - 50, 11 - 50 employees, 51 - 200, 51 - 200 employees, 201 - 500, 201 - 500 employees, 501 - 1,000, 501 - 1,000 employees, 1,001 - 5,000, 1,001 - 5,000 employees, 5,001 - 10,000, 5,001 - 10,000 employees, 10,001+, 10,001+ employees.Up to 10 items.
string[]
Filter by company annual revenue range. Provide multiple ranges to cover a broader span (e.g. [“$1M - $5M”, “$5M - $20M”] for $1M-$20M). Values must match exactly.One of: $0 - $100K, $100K - $1M, $1M - $5M, $5M - $20M, $20M - $50M, $50M - $100M, $100M - $500M, $500M - $1B, $1B+.Up to 10 items.
string
Only return contacts modified after this date (ISO 8601, e.g. 2025-01-01T00:00:00Z).
string
Only return contacts modified before this date (ISO 8601, e.g. 2025-12-31T23:59:59Z).
string[]
Filter by company type (Public or Private).One of: Public, Private.Up to 2 items.
string[]
Filter by total funding amount range (e.g. [“$1M-$5M”, “$5M-$20M”]).One of: $0-$100K, $100K-$1M, $1M-$5M, $5M-$20M, $20M-$50M, $50M-$100M, $100M-$500M, $500M-$1B, $1B+.
string[]
Filter by latest funding round type (e.g. [“Seed”, “Series A”]).One of: Angel, Pre-Seed, Seed, Series A, Series B, Series C, Series D, Series E, Series F, Series G, Series H, Series I, Series J, Other.
string[]
Filter by recency of latest funding round: “90” = last 90 days, “180” = last 180 days, “365” = last year, “1095” = last 3 years.One of: 90, 180, 365, 1095.Up to 4 items.
string[]
Free-text keywords matched against the contact record (e.g. [“machine learning”]).Up to 10 items.
boolean
default:"false"
How to combine multiple positive contactKeyword values: false (default) requires ALL of them, true matches ANY of them. Values prefixed with ”-” are always excluded in either mode.
string[]
Filter by technologies used by the company (e.g. [“Salesforce”, “AWS”]).Up to 100 items.
boolean
default:"true"
How to combine multiple technologies: true (default) matches ANY of them, false requires ALL of them.
string[]
Filter by company news/event type (e.g. [“Acquisition”, “Investment”]). Pair with newsTypeDates to bound recency.One of: Acquisition, Corporate Challenges, Cost Cutting, Expansion, Investment, Leadership, Partnership, Recognition.Up to 8 items.
string[]
Recency window for newsTypes, in days: “60”, “90”, “180”, or “365”. Accepts a single value.One of: 60, 90, 180, 365.Up to 1 item.
object
Filter to contacts who recently changed jobs. Omit a sub-field to let search pick its default.
object
Filter to contacts who previously worked at these companies and no longer work there. Names always match on relevance, so aliases and name fragments match too.
string[]
Filter by email address. Finds contacts matching these email addresses.Up to 100 items.
string[]
Filter by phone number. Accepts any format (e.g. “+1 (555) 123-4567”); non-digit characters are stripped automatically.Up to 100 items.

Result

Returns a text content block and a structuredContent object with these fields. Treat every field as nullable: a value the record does not have comes back as null.
object[]
required
Result records for the current page
object
Pagination metadata when available. Carries only the values the service has, so treat a missing key as unknown rather than zero; nextCursor is null or absent on the last page. Also reports the credit usage for this page.

Example

search_companies

Search the Seamless.AI database for companies matching filters like name, domain, industry, size, and revenue. Returns a paginated table of matching companies. Costs 1 credit per 50 results returned, rounded up; a page is trimmed to the rows the remaining credits cover. For companies you have already saved, use get_my_companies instead.

Arguments

string
Opaque token from pagination.nextCursor
integer
Page size (default 50). Must match the first page’s when cursor is set
integer | string
Run the filters held by a saved search, found via list_saved_searches. Cannot be combined with other filters.
string[]
Filter by company names.Up to 100 items.
string[]
Deprecated alias for companyName. Prefer companyName.Up to 100 items.
string
default:"default"
Company name match type.One of: default, related, exact.
string[]
Filter by company domains.Up to 100 items.
string[]
Filter by company state, matching any of them (e.g. [“Texas”, “California”]). Narrowed by companyCountry when both are given. Prefix a value with ”-” to exclude it; an excluded state stands alone, since exclusions narrow on their own.Up to 10 items.
string[]
Filter by company country (e.g. [“United States”]). Narrows companyState rather than widening it, but does not narrow locations — put the country in the tag itself (e.g. “Austin, Texas, United States”) to scope a free-form tag. A state and country that do not belong together narrow to nothing and are rejected: companyState [“Texas”] with companyCountry [“Germany”] is an error that names the real country for that state, since no company is in both — use locations when you mean either place rather than both. Prefix a value with ”-” to exclude it; an excluded country stands alone and narrows nothing.Up to 10 items.
string[]
Filter by company zip code. Widens the other location filters rather than narrowing them — a company matches any of these zip codes, or anything locations/companyState ask for — so send it alone to match zip codes only. Prefix a value with ”-” to exclude it.Up to 10 items.
string[]
Filter by free-form location tags — city, state/region, or country, and the only way to filter by city (e.g. [“Austin, Texas”, “Ontario, Canada”]). Prefix a value with ”-” to exclude it. Matches any of them, and any companyState too.Up to 10 items.
string | number
Widen every company location filter, companyZipCode included, to everything within a radius of each value. The value is the radius in miles: 25, 50, 100, or 250. Only geocodable values (cities, zip codes) get a radius.One of: 25, 50, 100, 250.
string[]
Filter by industry (e.g. [“Financial Services”, “-Staffing and Recruiting”]). Prefix a value with ”-” to exclude it.Up to 5 items.
(string | integer)[]
Filter by SIC code, independently of industry (e.g. [“7372”, “-5734”]). Prefix a value with ”-” to exclude it.Up to 5 items.
(string | integer)[]
Filter by NAICS code, independently of industry (e.g. [“511210”, “-561310”]). Prefix a value with ”-” to exclude it. Matched against the company’s own naicsCode; a company that has no naicsCode also matches when its SIC code maps to a requested code.Up to 5 items.
string[]
Filter by company employee count range. Provide multiple ranges to cover a broader span (e.g. [“11 - 50”, “51 - 200”] for 11-200 employees). Values must match exactly.One of: 0 - 1 (Self-employed), Self-employed, 2 - 10, 2 - 10 employees, 11 - 50, 11 - 50 employees, 51 - 200, 51 - 200 employees, 201 - 500, 201 - 500 employees, 501 - 1,000, 501 - 1,000 employees, 1,001 - 5,000, 1,001 - 5,000 employees, 5,001 - 10,000, 5,001 - 10,000 employees, 10,001+, 10,001+ employees.Up to 10 items.
string[]
Deprecated alias for companySize. Prefer companySize.One of: 0 - 1 (Self-employed), Self-employed, 2 - 10, 2 - 10 employees, 11 - 50, 11 - 50 employees, 51 - 200, 51 - 200 employees, 201 - 500, 201 - 500 employees, 501 - 1,000, 501 - 1,000 employees, 1,001 - 5,000, 1,001 - 5,000 employees, 5,001 - 10,000, 5,001 - 10,000 employees, 10,001+, 10,001+ employees.Up to 10 items.
string[]
Filter by company annual revenue range. Provide multiple ranges to cover a broader span (e.g. [“$1M - $5M”, “$5M - $20M”] for $1M-$20M). Values must match exactly.One of: $0 - $100K, $100K - $1M, $1M - $5M, $5M - $20M, $20M - $50M, $50M - $100M, $100M - $500M, $500M - $1B, $1B+.Up to 10 items.
string[]
Deprecated alias for companyRevenue. Prefer companyRevenue.One of: $0 - $100K, $100K - $1M, $1M - $5M, $5M - $20M, $20M - $50M, $50M - $100M, $100M - $500M, $500M - $1B, $1B+.Up to 10 items.
string[]
Filter by years since the company was founded.One of: Less than 1 Year, Last 1-3 Years, Last 4-10 Years, 10+ Years.Up to 4 items.
string[]
Filter by company type (Public or Private).One of: Public, Private.Up to 2 items.
string[]
Filter by total funding amount range (e.g. [“$1M-$5M”, “$5M-$20M”]).One of: $0-$100K, $100K-$1M, $1M-$5M, $5M-$20M, $20M-$50M, $50M-$100M, $100M-$500M, $500M-$1B, $1B+.
string[]
Filter by latest funding round type (e.g. [“Seed”, “Series A”]).One of: Angel, Pre-Seed, Seed, Series A, Series B, Series C, Series D, Series E, Series F, Series G, Series H, Series I, Series J, Other.
string[]
Filter by recency of latest funding round: “90” = last 90 days, “180” = last 180 days, “365” = last year, “1095” = last 3 years.One of: 90, 180, 365, 1095.Up to 4 items.
string[]
Free-text keywords matched against the company record (e.g. [“renewable energy”]). Prefix with ”-” to exclude; excluded keywords always narrow the results regardless of keywordsIsOr.Up to 10 items.
boolean
default:"false"
How to combine multiple positive companyKeyword values: false (default) requires ALL of them, true matches ANY of them. Values prefixed with ”-” are always excluded in either mode.
string[]
Filter by technologies used by the company (e.g. [“Salesforce”, “AWS”]).Up to 100 items.
boolean
default:"true"
How to combine multiple technologies: true (default) matches ANY of them, false requires ALL of them.
string[]
Filter by company news/event type (e.g. [“Acquisition”, “Investment”]). Pair with newsTypeDates to bound recency.One of: Acquisition, Corporate Challenges, Cost Cutting, Expansion, Investment, Leadership, Partnership, Recognition.Up to 8 items.
string[]
Recency window for newsTypes, in days: “60”, “90”, “180”, or “365”. Accepts a single value.One of: 60, 90, 180, 365.Up to 1 item.

Result

Returns a text content block and a structuredContent object with these fields. Treat every field as nullable: a value the record does not have comes back as null.
object[]
required
Result records for the current page
object
Pagination metadata when available. Carries only the values the service has, so treat a missing key as unknown rather than zero; nextCursor is null or absent on the last page. Also reports the credit usage for this page.

Example

lookup_locations

Search the location vocabulary for the exact spellings a location filter will match, most common first. Use this whenever you are unsure how the data spells a place, and before setting any location filter on search_contacts, search_companies, or a saved search: spellings follow the data rather than the local exonym (Germany’s state is “Bavaria”, not “Bayern”), and a value the vocabulary does not hold is rejected. Each result carries the contact count behind it, which is what disambiguates a name that means several places (“Ontario” is a Canadian province and five US cities), and a type naming which filter the value belongs on. US state abbreviations and country aliases like “TX” and “USA” are accepted by the filters directly and need no lookup.

Arguments

string
required
Partial location name, matched at the start of any word — “york” finds “New York”. Search one place name at a time, not a whole tag.
integer
Maximum results to return. Defaults to 10, max 100.
string[]
Restrict to these tiers of the vocabulary. Omit for all. Use “state-country” or “country” to find a value for contactState/companyState or contactCountry/companyCountry, “city-state-country” for a locations tag, and “postcode” for contactZipCode/companyZipCode.One of: city-state-country, state-country, city-country, country, postcode.

Result

Returns a text content block and a structuredContent object with these fields. Treat every field as nullable: a value the record does not have comes back as null.
object[]
required
Result records for the current page
object
Pagination metadata when available. Carries only the values the service has, so treat a missing key as unknown rather than zero; nextCursor is null or absent on the last page.

Example