> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Icypeas The Icypeas connector lets your AI agent act in each user's Icypeas account. Each user connects their own Icypeas API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 23 tools. **Authentication:** API Key **Categories:** CRM & Sales, Marketing **Tools:** 23: 19 read, 4 write, 0 destructive **Users sign in with:** API key **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=ICYPEAS) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Icypeas connection In **AgentKit > Connections**, create an Icypeas connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'icypeas' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Icypeas:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'icypeas_list_bulk_search_files', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "icypeas" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Icypeas:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="icypeas_list_bulk_search_files", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user opens the link once and enters their Icypeas credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'icypeas_count_companies', toolInput: { query: {}, }, connector: 'icypeas', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="icypeas_count_companies", tool_input={ "query": {}, }, connection_name="icypeas", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `icypeas_count_companies` Count Companies · Read-only Count the companies in the Icypeas company database that match a filter query, without returning them. Returns success and the number of matching companies. Use this to size a query before icypeas_find_companies. It is free; rate limit is 10 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `query` (`object`, required): The search query as an object mapping filter names to conditions. Text filters take an object with include and/or exclude arrays (up to 200 values each), and numeric filters take comparison operators such as >, <, >=, <=. Available filters: name, lid (LinkedIn public id), urn, companyId, domain, type, industry, location, keyword, headcount, revenue and headcountGrowth (an object with min, max and a timespan of 6months, 12months or 24months). Example: {"industry": {"include": ["Real Estate"]}, "location": {"include": ["FR"]}, "headcount": {">": 10}}. Example input: `{"query":{}}` ### `icypeas_count_people` Count People · Read-only Count the people in the Icypeas lead database that match a filter query, without returning them. Returns success and the number of matching people. Use this to size a query before icypeas_find_people. It is free; rate limit is 10 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `query` (`object`, required): The search query as an object mapping filter names to conditions. Text filters take an object with include and/or exclude arrays (up to 200 values each), and numeric filters take comparison operators such as >, <, >=, <=. Person filters: firstname, lastname, currentJobTitle, pastJobTitle, school, languages, skills, location, profileLocation, workLocation, keyword, totalYearsOfExperience, timeInCurrentCompany. Company filters come in current and past forms: currentCompanyName, currentCompanyId, currentCompanyWebsite, currentCompanyUrn, currentCompany.type, currentCompany.industry, currentCompany.location, currentCompany.headcount, currentCompany.headcountGrowth, currentCompany.revenue, currentCompany.keyword, and the same with a pastCompany prefix. Example: {"currentJobTitle": {"include": ["CTO"]}, "location": {"include": ["US"]}, "currentCompany.headcount": {">": 10}}. Example input: `{"query":{}}` ### `icypeas_find_companies` Find Companies · Read-only Search the Icypeas company database for companies matching a filter query. Returns success, a total count, a leads array of matching companies (name, website, industry, headcount and similar) and a pagination object with a token when more pages exist. Use icypeas_count_companies first to size a query for free, then this tool to fetch results. Use icypeas_find_people to search people instead. Costs 0.02 credit per result returned; rate limit is 30 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `query` (`object`, required): The search query as an object mapping filter names to conditions. Text filters take an object with include and/or exclude arrays (up to 200 values each), and numeric filters take comparison operators such as >, <, >=, <=. Available filters: name, lid (LinkedIn public id), urn, companyId, domain, type, industry, location, keyword, headcount, revenue and headcountGrowth (an object with min, max and a timespan of 6months, 12months or 24months). Example: {"industry": {"include": ["Real Estate"]}, "location": {"include": ["FR"]}, "headcount": {">": 10}}. - `page_size` (`integer`, optional): Number of companies to return per page, from 1 to 200. Defaults to 100. - `pagination_token` (`string`, optional): Pagination token from the pagination object of the previous response. Pass it together with the same query and page size to fetch the next page. Tokens expire. Example input: `{"query":{}}` ### `icypeas_find_company_url` Find Company URL · Read-only Find the LinkedIn company URL of one company from its name or domain. Returns success and the company URL when one is found. Use this to discover a company URL, then icypeas_scrape_company to read it. Use icypeas_find_company_urls_bulk for up to 50 companies. Costs 1 credit per URL found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `company_or_domain` (`string`, required): Company name, or its domain or website. Example input: `{"company_or_domain":""}` ### `icypeas_find_company_urls_bulk` Find Company URLs (Bulk) · Read-only Find LinkedIn company URLs for up to 50 companies in one request. Returns success and the outcome of the batch for the submitted companies. Use this for several companies at once; use icypeas_find_company_url for one. Costs 1 credit per URL found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `companies` (`array`, required): Array of companies to find. Each item is an object with companyOrDomain set to a company name or domain, for example {"companyOrDomain": "nec technologies"}. Maximum 50 items. Example input: `{"companies":[]}` ### `icypeas_find_people` Find People · Read-only Search the Icypeas lead database for people matching a filter query. Returns success, a total count, a leads array of matching people and a pagination object with a token when more pages exist. Use icypeas_count_people first to size a query for free, then this tool to fetch results. Use icypeas_find_companies to search companies instead. Costs 0.02 credit per result returned; rate limit is 30 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `query` (`object`, required): The search query as an object mapping filter names to conditions. Text filters take an object with include and/or exclude arrays (up to 200 values each), and numeric filters take comparison operators such as >, <, >=, <=. Person filters: firstname, lastname, currentJobTitle, pastJobTitle, school, languages, skills, location, profileLocation, workLocation, keyword, totalYearsOfExperience, timeInCurrentCompany. Company filters come in current and past forms: currentCompanyName, currentCompanyId, currentCompanyWebsite, currentCompanyUrn, currentCompany.type, currentCompany.industry, currentCompany.location, currentCompany.headcount, currentCompany.headcountGrowth, currentCompany.revenue, currentCompany.keyword, and the same with a pastCompany prefix. Example: {"currentJobTitle": {"include": ["CTO"]}, "location": {"include": ["US"]}, "currentCompany.headcount": {">": 10}}. - `page_size` (`integer`, optional): Number of people to return per page, from 1 to 200. Defaults to 100. - `pagination_token` (`string`, optional): Pagination token from the pagination object of the previous response. Pass it together with the same query and page size to fetch the next page. Tokens expire. Example input: `{"query":{}}` ### `icypeas_find_profile_url` Find Profile URL · Read-only Find the LinkedIn profile URL of one person from a name plus a company or a job title. Returns success and the profile URL when one is found. Use this to discover a profile URL, then icypeas_scrape_profile to read it. Use icypeas_find_profile_urls_bulk for up to 50 people. Costs 1 credit per URL found; rate limit is 20 calls per second. Provide company_or_domain or job_title in addition to the name. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `firstname` (`string`, required): First name of the person to find. - `lastname` (`string`, required): Last name of the person to find. - `company_or_domain` (`string`, optional): Company name or company domain or website of the person. Required unless job_title is given. - `job_title` (`string`, optional): Job title of the person. Required unless company_or_domain is given. Example input: `{"firstname":"","lastname":""}` ### `icypeas_find_profile_urls_bulk` Find Profile URLs (Bulk) · Read-only Find LinkedIn profile URLs for up to 50 people in one request. Returns success and the outcome of the batch for the submitted people. Use this for several people at once; use icypeas_find_profile_url for one. Costs 1 credit per URL found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `people` (`array`, required): Array of people to find. Each item is an object with firstname and lastname plus companyOrDomain or jobTitle, for example {"firstname": "Marc", "lastname": "Lachabody", "companyOrDomain": "nec technologies"}. Maximum 50 items. Example input: `{"people":[]}` ### `icypeas_get_search_result` Get Search Result · Read-only Fetch the result of one search item by its _id. Returns success and an items array with the item status (NONE, SCHEDULED, IN_PROGRESS, FOUND, DEBITED, NOT_FOUND, BAD_INPUT and others) and, when finished, its results such as emails with certainty. Use this to read the outcome of a single search or one row of a bulk search; poll until the status is final. Use icypeas_list_bulk_search_results to page through a whole bulk search. Rate limit is 30 calls per minute. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `id` (`string`, required): The _id returned when the search was started (or the _id of a row within a bulk search). Example input: `{"id":""}` ### `icypeas_get_subscription` Get Subscription Information · Read-only Retrieve the subscription plan, remaining credits and user id for an Icypeas account. Returns success and the subscription and credit details for the given email. Use this to check credits before running paid searches. It is free. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `email` (`string`, required): The email address of the Icypeas user whose subscription you want. Example input: `{"email":""}` ### `icypeas_list_bulk_search_files` List Bulk Search Files · Read-only List your bulk searches (files) with their progress and statistics, optionally only in-progress or done ones, or one specific file. Returns success, the matching files with status and stats, and a sorts cursor for the next page. Use this to check whether a bulk search started with icypeas_bulk_search has finished. Use icypeas_list_bulk_search_results to read its rows. Maximum 50 files per request; rate limit is 15 calls per minute. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `file` (`string`, optional): Return only this bulk file, by its id. - `limit` (`integer`, optional): Number of files to return. Default 10, maximum 50. - `next` (`boolean`, optional): When paginating with sorts, true fetches the next page and false the previous page. - `sorts` (`array`, optional): Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag. - `status` (`string`, optional): Only return bulk searches with this status: in_progress or done. One of: `in_progress`, `done`. Example input: `{}` ### `icypeas_list_bulk_search_results` List Bulk Search Results · Read-only List the result rows of one bulk search, or of all bulk searches, in insertion order. Returns success, an items array of search items with status and results, a total count and a sorts cursor for the next page. Use this after icypeas_bulk_search to read its rows. Use icypeas_get_search_result for one item and icypeas_list_single_searches for single searches. Maximum 100 rows per request; rate limit is 30 calls per minute. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `file` (`string`, optional): The bulk file id returned by icypeas_bulk_search. If omitted, rows from all your bulk searches are returned, newest first. - `limit` (`integer`, optional): Number of rows to return. Default 10, maximum 100. - `next` (`boolean`, optional): When paginating with sorts, true fetches the next page and false the previous page. - `sorts` (`array`, optional): Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag. Example input: `{}` ### `icypeas_list_single_searches` List Single Searches · Read-only List your single (non-bulk) searches, newest first, optionally filtered by search type. Returns success, an items array of search items with status and results, a total count and a sorts cursor for the next page. Use this to review past single searches. Use icypeas_list_bulk_search_results for bulk rows and icypeas_get_search_result for one item by _id. Maximum 100 per request; rate limit is 30 calls per minute. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Number of items to return. Default 10, maximum 100. - `next` (`boolean`, optional): When paginating with sorts, true fetches the next page and false the previous page. - `sorts` (`array`, optional): Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag. - `type` (`string`, optional): Only return single searches of this type, for example email-search, email-verification or domain-search. Example input: `{}` ### `icypeas_reverse_email_lookup` Reverse Email Lookup · Read-only Find the profile URL behind one professional email address. Returns success and the lookup outcome with the profile URL when one is found. Use this to go from an email to a profile. Use icypeas_reverse_email_lookup_bulk for 2 to 50 addresses. Costs 10 credits per profile found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `email` (`string`, required): A professional email address to look up. Example input: `{"email":""}` ### `icypeas_reverse_email_lookup_bulk` Reverse Email Lookup (Bulk) · Read-only Find the profile URLs behind 2 to 50 professional email addresses in one request. Returns success and the outcome of the batch lookup for the submitted addresses. Use this for several addresses at once. Use icypeas_reverse_email_lookup for a single address. Costs 10 credits per profile found. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `emails` (`array`, required): Array of professional email addresses. Minimum 2, maximum 50. Example input: `{"emails":[]}` ### `icypeas_scrape_companies_bulk` Scrape Companies (Bulk) · Read-only Scrape up to 50 companies from their LinkedIn company URLs in one request. Returns success and the outcome of the batch for the submitted company URLs. Use this for several companies at once; use icypeas_scrape_company for one. Costs 0.5 credit per company found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `urls` (`array`, required): Array of LinkedIn company URLs to scrape. Maximum 50. Example input: `{"urls":[]}` ### `icypeas_scrape_company` Scrape Company · Read-only Scrape the data of one company from its LinkedIn company URL. Returns success and the company data when the company is found. Use this when you already have a company URL; use icypeas_find_company_url to discover the URL first and icypeas_scrape_companies_bulk for up to 50 companies. Costs 0.5 credit per company found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `url` (`string`, required): The LinkedIn company URL to scrape, for example https://www.linkedin.com/company/nec-technologies. Example input: `{"url":""}` ### `icypeas_scrape_profile` Scrape Profile · Read-only Scrape the data of one professional profile from its LinkedIn URL. Returns success and the profile data when the profile is found. Use this when you already have a profile URL; use icypeas_find_profile_url to discover the URL first and icypeas_scrape_profiles_bulk for up to 50 profiles. Costs 1.5 credits per profile found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `url` (`string`, required): The LinkedIn profile URL to scrape, for example https://www.linkedin.com/in/corentin-ribeyre-30085a3b. Example input: `{"url":""}` ### `icypeas_scrape_profiles_bulk` Scrape Profiles (Bulk) · Read-only Scrape up to 50 professional profiles from their LinkedIn URLs in one request. Returns success and the outcome of the batch for the submitted profile URLs. Use this for several profiles at once; use icypeas_scrape_profile for one. Costs 1.5 credits per profile found; rate limit is 20 calls per second. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `urls` (`array`, required): Array of LinkedIn profile URLs to scrape. Maximum 50. Example input: `{"urls":[]}` ### `icypeas_bulk_search` Start Bulk Search · Write Start a bulk search that runs email discovery, email verification or domain scanning over up to 5000 rows. Returns success, the bulk file id and its status (for example in_progress); results are fetched separately. Use this for many rows at once. Check progress with icypeas_list_bulk_search_files and read rows with icypeas_list_bulk_search_results. Use the single-search tools for one item. Rate limit is 1 call per second. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `data` (`array`, required): The rows to process, as an array of rows where each row is itself an array of strings. For email-search each row has three items: first name, last name and domain or company, for example ["John", "Doe", "icypeas.com"] (first or last name may be an empty string but not both). For email-verification each row is a single email address, for example ["john.doe@icypeas.com"]. For domain-search each row is a single domain or company name, for example ["icypeas.com"]. Maximum 5000 rows. - `name` (`string`, required): A name for this bulk search so you can find it later. - `task` (`string`, required): The type of search to run on every row. One of email-search, email-verification or domain-search. One of: `email-search`, `email-verification`, `domain-search`. - `external_ids` (`array`, optional): Your own identifiers, one per row, in the same order and with the same length as data. Not checked for uniqueness. Example input: `{"data":[],"name":"","task":"email-search"}` ### `icypeas_domain_search` Scan Domain for Role Emails · Write Start a domain scan that discovers role-based email addresses such as contact@ or admin@ for one domain or company. Returns success and an item with the search _id and its initial status; the addresses are not in this response. Use this to find generic company mailboxes, then call icypeas_get_search_result with the _id. Use icypeas_email_search to find a named person's address. Costs 1 credit if emails are found. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `domain_or_company` (`string`, required): The domain or company name to scan, for example icypeas.com. - `external_id` (`string`, optional): Your own identifier for this search. It is stored with the search item so you can match results back to your records. Not checked for uniqueness. Example input: `{"domain_or_company":""}` ### `icypeas_email_search` Find Email Address · Write Start an email discovery search for one person from a first name, last name and company domain or name. Returns success and an item with the search _id and its initial status (usually NONE); the email is not in this response. Use this for one prospect, then call icypeas_get_search_result with the _id until the status is final. Use icypeas_bulk_search for many prospects. Costs 1 credit per email found. Provide at least one of firstname or lastname. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `domain_or_company` (`string`, required): Company domain or company name where the person works, for example icypeas.com or Icypeas. - `firstname` (`string`, required): First name of the person. Can be an empty string if lastname is provided. - `lastname` (`string`, required): Last name of the person. Can be an empty string if firstname is provided. - `external_id` (`string`, optional): Your own identifier for this search. It is stored with the search item so you can match results back to your records. Not checked for uniqueness. Example input: `{"domain_or_company":"","firstname":"","lastname":""}` ### `icypeas_email_verification` Verify Email Address · Write Start a verification search to check whether one email address exists and can receive mail. Returns success and an item with the search _id and its initial status; the verdict is not in this response. Use this for a single address, then call icypeas_get_search_result with the _id. Use icypeas_bulk_search with task email-verification for many addresses. Costs 0.1 credit per tested email. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `email` (`string`, required): The email address to verify. - `external_id` (`string`, optional): Your own identifier for this search. It is stored with the search item so you can match results back to your records. Not checked for uniqueness. Example input: `{"email":""}` ## Related Other CRM & Sales connectors ([all 97](/agentkit/connectors/?category=crm-sales)): - [Insightly](/agentkit/connectors/insightly/): Scalekit connector, API key, 108 tools - [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools - [Salesforce](/agentkit/connectors/salesforce/): Scalekit connector, OAuth, 74 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |