List Contact Segment
list_contact_segmentReturn a filtered contact segment using the same criteria as the web search page. Consumes the account's shared subscription balance (the same balance used by subscribed Excel exports and REST API usage: included monthly contacts first, then prepaid top-up contacts). A completed call always costs at least 1 unit. Costs 1 contact unit per returned contact row. Results are deterministically ordered and support limit/offset pagination. Response meta includes companyCount (number of distinct companies represented by matching contacts). Returned contact rows include person fields (name, title, email, phone, responsibility areas), compact employer context (companyId, companyName, countryName, region, city, wwwpage, industryName), and source classification attributes (hasWebshop, webshopPlatform, targetMarket). Full company descriptions, financials, and address details are omitted; use find_companies or list_company_segment for full company details. Supports webshopStatus, webshopPlatforms, and targetMarket filters. webshopPlatforms is only valid when webshopStatus is "identified" or omitted. Supports company keyword taxonomy filtering through keywordCategoryFilter. Use list_keyword_categories for broad main categories and search_keyword_subcategories for specific business activities. Pass only canonical returned name values; never pass localized labels or raw keywords. Your account exclusion list always applies automatically and cannot be disabled. Optional customerListMode: "exclude" removes companies on your customer list (net-new prospecting), "limit" returns only customer-list companies, "ignore" or omitted ignores the customer list. Exclude/limit require an active customer list managed in the web app (Company lists). For count-only questions, prefer count_contact_segment. Example: list_contact_segment({ countryId: -2460, contactInfoFilter: "both", organizationLevels: ["Top Management"], limit: 50, offset: 0 }).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of contacts to return. Defaults to 100; cannot exceed 100. Use a small value such as 3 when only sample rows are needed. | |
| offset | No | Zero-based offset for paginating deterministic results. Use with limit. | |
| companyId | No | Optional company ID filter. Restricts results to one company when provided. | |
| countryId | Yes | Country ID. Use list_countries to discover valid values. Note: IDs are negative integers as stored in the database (e.g. Finland = -2460, Sweden = -7520, Estonia = -2330). | |
| profitMax | No | In thousands of euros (EUR thousands). Maximum annual profit; negative values are allowed and represent net loss. | |
| profitMin | No | In thousands of euros (EUR thousands). Minimum annual profit; negative values are allowed and represent net loss. | |
| businessId | No | Optional company business ID filter. Normalizes dashes/spaces when matching (e.g. "1234567-8"). | |
| regionName | No | Region/province name (case-insensitive substring match). Use the local-language name as shown in company records, e.g. "Uusimaa", "Stockholm". | |
| turnoverMax | No | In thousands of euros (EUR thousands). Maximum annual turnover. Example: 5000 = EUR 5M turnover. | |
| turnoverMin | No | In thousands of euros (EUR thousands). Minimum annual turnover. Example: 5000 = EUR 5M turnover. | |
| personnelMax | No | Maximum number of employees (headcount) as reported in company records. | |
| personnelMin | No | Minimum number of employees (headcount) as reported in company records. | |
| targetMarket | No | Target market classification: "b2b" = B2B only (1), "b2c" = B2C only (2), "both" = both B2B and B2C (12), "unknown" = crawled but unknown (0), "not_crawled" = not yet crawled (NULL). Omitted includes every state. | |
| industryCodes | No | Industry codes (NACE/TOL) for filtering companies and contacts. Codes match by prefix: a full code like "62010" matches one industry, while a shorter prefix like "62" matches every industry whose code starts with it. Call list_industries first to discover valid codes, then pass the returned id values here. IDs from list_industries are string-typed numeric codes, not integers — pass them as strings. | |
| webshopStatus | No | Webshop classification filter: "identified" = a webshop was found, "not_identified" = crawled and no webshop found, "not_crawled" = not yet crawled. Omitted includes all states including 0 and NULL. | |
| foundedYearMax | No | Latest founding year to include (e.g. 2020). | |
| foundedYearMin | No | Earliest founding year to include (e.g. 2010). | |
| jobFunctionIds | No | Job function IDs for multi-select filters. Use list_job_functions to discover valid values. Finer-grained than mainResponsibilityAreaIds. | |
| customerListMode | No | Optional customer-list mode: "exclude" removes companies on your customer list (net-new prospecting), "limit" returns only customer-list companies that match the other filters, "ignore" or omitted ignores the customer list. "exclude"/"limit" require an active customer list managed in the web app under Company lists; fails with CUSTOMER_LIST_REQUIRED otherwise. The account exclusion list always applies regardless of this setting. | |
| industryGroupIds | No | Industry group IDs for multi-select filters. Use list_industry_groups to discover valid values. | |
| webshopPlatforms | No | Webshop platform names (e.g. "shopify", "woocommerce"). Must be combined with webshopStatus "identified" or omitted; combining with "not_identified" or "not_crawled" is invalid. Values are normalized to lowercase/trimmed. Up to 20 values, each up to 50 characters. | |
| contactInfoFilter | No | Contact-level required info filter: "email" (default) = each returned contact must have valid email, "phone" = must have phone number, "both" = must have both, "either" = must have a valid email, a phone number, or both. Use companyContactFilter on company-segment tools when filtering companies by whether they have at least one matching contact. | |
| organizationLevels | No | Hierarchy level filter; orthogonal to mainResponsibilityAreaIds/jobFunctionIds. Combine with responsibility filters for e.g. Sales + Top Management. | |
| keywordCategoryFilter | No | Company keyword taxonomy filter. Use level "main" only with canonical name values returned by list_keyword_categories and level "sub" only with canonical name values returned by search_keyword_subcategories. Copy the returned name, not a localized labels value. any matches at least one item, all requires every item, and none excludes every item; non-empty buckets combine with AND. This filters classified company categories and subcategories, not raw keyword text. | |
| newContactsWithinDays | No | Returns contacts created within the last N days (max 3650). | |
| mainResponsibilityAreaIds | No | Broad functional responsibility area IDs (e.g. IT, Marketing). Use list_main_responsibility_areas to discover valid values. IDs are negative integers as stored in the database (e.g. Sales = -70, IT = -40, Marketing = -60, HR = -30, Finances = -50, Managing Director = -20). Combine with jobFunctionIds or organizationLevels to narrow further. | |
| newResponsibilityAssignmentsWithinDays | No | Returns contacts with an assignment created within the last N days (max 3650). |