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.
- Tools
- 23
- What they doRead · write · destructive
- 19 · 4 · 019 read4 write0 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Icypeas connection
In AgentKit > Connections, create an Icypeas connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts 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.actionsconst connector = 'icypeas'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'icypeas_list_bulk_search_files',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_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.actionsconnection_name = "icypeas"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="icypeas_list_bulk_search_files",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Icypeas credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolicypeas_count_companiesCount the companies in the Icypeas company database that match a filter query, without returning them.Read-onlyCount Companies
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.
Inputs
queryobjectrequired- 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}}.
icypeas_count_peopleCount the people in the Icypeas lead database that match a filter query, without returning them.Read-onlyCount People
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.
Inputs
queryobjectrequired- 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}}.
icypeas_find_companiesSearch the Icypeas company database for companies matching a filter query.Read-onlyFind Companies
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.
Inputs
queryobjectrequired- 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_sizeinteger- Number of companies to return per page, from 1 to 200. Defaults to 100.
pagination_tokenstring- 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.
icypeas_find_company_urlFind the LinkedIn company URL of one company from its name or domain.Read-onlyFind Company URL
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.
Inputs
company_or_domainstringrequired- Company name, or its domain or website.
icypeas_find_company_urls_bulkFind LinkedIn company URLs for up to 50 companies in one request.Read-onlyFind Company URLs (Bulk)
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.
Inputs
companiesarrayrequired- 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.
icypeas_find_peopleSearch the Icypeas lead database for people matching a filter query.Read-onlyFind People
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.
Inputs
queryobjectrequired- 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_sizeinteger- Number of people to return per page, from 1 to 200. Defaults to 100.
pagination_tokenstring- 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.
icypeas_find_profile_urlFind the LinkedIn profile URL of one person from a name plus a company or a job title.Read-onlyFind Profile URL
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.
Inputs
firstnamestringrequired- First name of the person to find.
lastnamestringrequired- Last name of the person to find.
company_or_domainstring- Company name or company domain or website of the person. Required unless job_title is given.
job_titlestring- Job title of the person. Required unless company_or_domain is given.
icypeas_find_profile_urls_bulkFind LinkedIn profile URLs for up to 50 people in one request.Read-onlyFind Profile URLs (Bulk)
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.
Inputs
peoplearrayrequired- 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.
icypeas_get_search_resultFetch the result of one search item by its _id.Read-onlyGet Search Result
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.
Inputs
idstringrequired- The _id returned when the search was started (or the _id of a row within a bulk search).
icypeas_get_subscriptionRetrieve the subscription plan, remaining credits and user id for an Icypeas account.Read-onlyGet Subscription Information
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.
Inputs
emailstringrequired- The email address of the Icypeas user whose subscription you want.
icypeas_list_bulk_search_filesList your bulk searches (files) with their progress and statistics, optionally only in-progress or done ones, or one specific file.Read-onlyList Bulk Search Files
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.
Inputs
filestring- Return only this bulk file, by its id.
limitinteger- Number of files to return. Default 10, maximum 50.
nextboolean- When paginating with sorts, true fetches the next page and false the previous page.
sortsarray- Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag.
statusstring- Only return bulk searches with this status: in_progress or done.one of
in_progressdone
icypeas_list_bulk_search_resultsList the result rows of one bulk search, or of all bulk searches, in insertion order.Read-onlyList Bulk Search Results
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.
Inputs
filestring- The bulk file id returned by icypeas_bulk_search. If omitted, rows from all your bulk searches are returned, newest first.
limitinteger- Number of rows to return. Default 10, maximum 100.
nextboolean- When paginating with sorts, true fetches the next page and false the previous page.
sortsarray- Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag.
icypeas_list_single_searchesList your single (non-bulk) searches, newest first, optionally filtered by search type.Read-onlyList Single Searches
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.
Inputs
limitinteger- Number of items to return. Default 10, maximum 100.
nextboolean- When paginating with sorts, true fetches the next page and false the previous page.
sortsarray- Pagination cursor. Pass the sorts array exactly as returned by the previous response to fetch another page, together with the next flag.
typestring- Only return single searches of this type, for example email-search, email-verification or domain-search.
icypeas_reverse_email_lookupFind the profile URL behind one professional email address.Read-onlyReverse Email Lookup
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.
Inputs
emailstringrequired- A professional email address to look up.
icypeas_reverse_email_lookup_bulkFind the profile URLs behind 2 to 50 professional email addresses in one request.Read-onlyReverse Email Lookup (Bulk)
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.
Inputs
emailsarrayrequired- Array of professional email addresses. Minimum 2, maximum 50.
icypeas_scrape_companies_bulkScrape up to 50 companies from their LinkedIn company URLs in one request.Read-onlyScrape Companies (Bulk)
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.
Inputs
urlsarrayrequired- Array of LinkedIn company URLs to scrape. Maximum 50.
icypeas_scrape_companyScrape the data of one company from its LinkedIn company URL.Read-onlyScrape Company
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.
Inputs
urlstringrequired- The LinkedIn company URL to scrape, for example https://www.linkedin.com/company/nec-technologies.
icypeas_scrape_profileScrape the data of one professional profile from its LinkedIn URL.Read-onlyScrape Profile
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.
Inputs
urlstringrequired- The LinkedIn profile URL to scrape, for example https://www.linkedin.com/in/corentin-ribeyre-30085a3b.
icypeas_scrape_profiles_bulkScrape up to 50 professional profiles from their LinkedIn URLs in one request.Read-onlyScrape Profiles (Bulk)
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.
Inputs
urlsarrayrequired- Array of LinkedIn profile URLs to scrape. Maximum 50.
icypeas_bulk_searchStart a bulk search that runs email discovery, email verification or domain scanning over up to 5000 rows.WriteStart Bulk Search
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.
Inputs
dataarrayrequired- 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.
namestringrequired- A name for this bulk search so you can find it later.
taskstringrequired- The type of search to run on every row. One of email-search, email-verification or domain-search.one of
email-searchemail-verificationdomain-search external_idsarray- Your own identifiers, one per row, in the same order and with the same length as data. Not checked for uniqueness.
icypeas_domain_searchStart a domain scan that discovers role-based email addresses such as contact@ or admin@ for one domain or company.WriteScan Domain for Role Emails
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.
Inputs
domain_or_companystringrequired- The domain or company name to scan, for example icypeas.com.
external_idstring- 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.
icypeas_email_searchStart an email discovery search for one person from a first name, last name and company domain or name.WriteFind Email Address
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.
Inputs
domain_or_companystringrequired- Company domain or company name where the person works, for example icypeas.com or Icypeas.
firstnamestringrequired- First name of the person. Can be an empty string if lastname is provided.
lastnamestringrequired- Last name of the person. Can be an empty string if firstname is provided.
external_idstring- 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.
icypeas_email_verificationStart a verification search to check whether one email address exists and can receive mail.WriteVerify Email Address
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.
Inputs
emailstringrequired- The email address to verify.
external_idstring- 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.
No tools match.
