The BetterContact connector lets your AI agent act in each user's BetterContact account. Each user connects their own BetterContact API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 9 tools.
- Tools
- 9
- What they doRead · write · destructive
- 5 · 4 · 05 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 BetterContact connection
In AgentKit > Connections, create a BetterContact 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 = 'bettercontact'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize BetterContact:', 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: 'bettercontact_enrich_company_profile',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 = "bettercontact"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize BetterContact:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="bettercontact_enrich_company_profile",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their BetterContact credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbettercontact_enrich_company_profileLook up one company by domain or LinkedIn URL and return its profile synchronously.Read-onlyEnrich Company Profile
Look up one company by domain or LinkedIn URL and return its profile synchronously. Returns name, domain, description, industry, size, founding year, headquarters, address, and keywords. Does not consume credits. Use create_company_finder_search to discover many companies by criteria. Provide company_domain, company_linkedin_url, or both.
Inputs
company_domainstring- Company website or domain. At least one of company_domain or company_linkedin_url is required. Example: microsoft.com.
company_linkedin_urlstring- LinkedIn page URL of the company. At least one of company_domain or company_linkedin_url is required. Example: https://www.linkedin.com/company/microsoft.
bettercontact_get_company_finder_resultsRetrieve the results of a Company Finder search.Read-onlyGet Company Finder Results
Retrieve the results of a Company Finder search. Returns the status, credits consumed and left, a summary with the total companies found, and the companies once the search finishes. A status of on_hold means there are not enough credits. Use after create_company_finder_search. While the status is processing, no companies are present, so call again after a short wait.
Inputs
request_idstringrequired- The request id returned when the Company Finder search was submitted. Example: bc39ffbfc24cf043b748.
bettercontact_get_credits_balanceRead the credit balance of the account the API key belongs to.Read-onlyGet Credits Balance
Read the credit balance of the account the API key belongs to. Returns credits_left and the account email. Use before submitting large enrichment or finder requests to check that enough credits remain.
Inputs
This tool takes no inputs.
bettercontact_get_enrichment_resultsRetrieve the results of an enrichment request submitted with enrich_leads.Read-onlyGet Enrichment Results
Retrieve the results of an enrichment request submitted with enrich_leads. Returns the request status, credits consumed and left, a summary, and the enriched leads with email, phone, and profile fields once the status is terminated. Use after enrich_leads. While the status is processing, no data is present, so call again after a short wait and branch on status rather than the HTTP code.
Inputs
request_idstringrequired- The request id returned when the enrichment request was submitted. Example: fefbc2203558eb3adcea.
bettercontact_get_lead_finder_resultsRetrieve the results of a Lead Finder search.Read-onlyGet Lead Finder Results
Retrieve the results of a Lead Finder search. Returns the status, credits consumed and left, a summary with the total leads found, and the leads once the status is terminated. A status of on_hold means credits must be topped up to resume. Use after create_lead_finder_search. While the status is processing, no leads are present, so call again after a short wait.
Inputs
request_idstringrequired- The request id returned when the Lead Finder search was submitted. Example: bc39ffbfc24cf043b748.
bettercontact_create_company_finder_searchStart an asynchronous search for companies by firmographic, funding, and hiring criteria.WriteCreate Company Finder Search
Start an asynchronous search for companies by firmographic, funding, and hiring criteria. Returns a request_id. The companies are not in this response. Use get_company_finder_results with the request_id to fetch companies. Use create_lead_finder_search to find people. Use enrich_company_profile for a single known company.
Inputs
filtersobjectrequired- Search criteria as an object. At least one filter must hold a value. List filters take only an include list: company (lowercase domains without a path), company_linkedin_url, company_industry, company_hq_location, company_technologies, company_keywords, company_description, revenue_ranges, last_funding_round_names, job_post_titles, job_posting_countries, job_posting_locations. Number filters are company_headcount_min and company_headcount_max. Boolean filters are is_b2b, is_b2c, and is_public. Range filters use gte and lte: last_funding_date_range (YYYY-MM-DD), last_amount_raised_usd, total_amount_raised_usd. Industry, technology, revenue range, and funding round values must match the vendor's fixed lists exactly. Example: {"company_industry": {"include": ["Software Development"]}, "company_hq_location": {"include": ["United States"]}, "company_headcount_min": 51, "company_headcount_max": 500, "is_b2b": true}.
limitinteger- Number of companies to return for this page, between 1 and 200. Defaults to 100 when omitted; a value above 200 is refused. Example: 25.
offsetinteger- Number of matches to skip. To page, keep limit constant and increase offset by limit each call; the total match count is in the results summary. Example: 25.
bettercontact_create_lead_finder_searchStart an asynchronous search for new leads by company and person criteria.WriteCreate Lead Finder Search
Start an asynchronous search for new leads by company and person criteria. Returns a request_id. The leads are not in this response. Use get_lead_finder_results with the request_id to fetch leads. Use create_company_finder_search to find companies instead of people. Optionally enriches emails or phones for each lead found, which consumes extra credits.
Inputs
filtersobjectrequired- Search criteria as an object. At least one filter must hold a value. Company filters take an include list: company (domains), company_linkedin_url, company_industry, company_hq_location, company_technologies, company_keywords, company_description, revenue_ranges, last_funding_round_names, job_post_titles, job_posting_countries, job_posting_locations. Lead filters take include and optional exclude lists: lead_fullname, lead_linkedin_url, lead_job_title (also accepts exact_match true or false), lead_seniority, lead_department, lead_function, lead_skills, lead_location. An exclude list needs at least one include alongside it. Number filters are company_headcount_min, company_headcount_max, and limit_per_company (1 to 100). Range filters use gte and lte: last_funding_date_range (YYYY-MM-DD), last_amount_raised_usd, total_amount_raised_usd. Boolean filters are is_b2b, is_b2c, and is_public. Industry, technology, seniority, department, revenue range, and funding round values must match the vendor's fixed lists exactly. Example: {"company_industry": {"include": ["Computer Software"]}, "lead_seniority": {"include": ["cxo", "vp"]}, "company_hq_location": {"include": ["United States"]}}.
enrich_email_addressboolean- Whether to also run waterfall email enrichment on every lead found. Consumes enrichment credits on top of the search, and results stay in processing until enrichment is done. Example: false.
enrich_phone_numberboolean- Whether to also run waterfall mobile phone enrichment on every lead found. Consumes enrichment credits and requires the phone add-on on your plan. Example: false.
limitinteger- Number of leads to return for this request, between 1 and 200. Use with offset to paginate. When omitted, up to 100 leads are returned. Example: 100.
offsetinteger- Number of leads to skip before returning matches. Only used when limit is set. To page, keep limit constant and increase offset by limit each call. Example: 100.
bettercontact_enrich_lead_profileLook up one person and return their profile and current company synchronously.WriteEnrich Lead Profile
Look up one person and return their profile and current company synchronously. Returns job title, seniority, LinkedIn headline, location, and company details. It does not return an email address or phone number. Use enrich_leads to get email or phone. Provide linkedin_url alone, or first_name, last_name and company_domain together. Costs 0.1 credit per profile found and nothing when no profile matches.
Inputs
companystring- Company name. Complements company_domain but cannot replace it. Example: Honda R&D Americas.
company_domainstring- Domain of the person's company. Required together with first_name and last_name when linkedin_url is not provided. Example: hondaresearch.com.
first_namestring- First name of the person. Required together with last_name and company_domain when linkedin_url is not provided. Example: Veronick.
last_namestring- Last name of the person. Required together with first_name and company_domain when linkedin_url is not provided. Example: Martinuzzi.
linkedin_urlstring- Public LinkedIn profile URL of the person. Sufficient on its own and takes precedence over the name fields. Example: https://www.linkedin.com/in/veronick-martinuzzi-a4533373.
bettercontact_enrich_leadsSubmit 1 to 100 leads for waterfall enrichment of work email, mobile phone, and LinkedIn profile.WriteEnrich Leads
Submit 1 to 100 leads for waterfall enrichment of work email, mobile phone, and LinkedIn profile. Returns a request id with status Processing. The enriched data is not in this response. Use get_enrichment_results with that id to fetch the data. Use enrich_lead_profile for a single synchronous profile lookup without email or phone. Consumes credits per enriched lead. Phone and catch-all verification need the matching plan add-ons.
Inputs
leadsarrayrequired- The leads to enrich, between 1 and 100. Each lead needs first_name and last_name, plus either company_domain or company (company_domain gives better results). Add linkedin_url for better phone results; it is required when enrich_profile is true. Add custom_fields, a free-form object, to have your own data such as a CRM record id echoed back with the result. Example: [{"first_name": "Elon", "last_name": "Musk", "company_domain": "tesla.com", "linkedin_url": "https://www.linkedin.com/in/elonmusk", "custom_fields": {"crm_id": "8821"}}].
enrich_email_addressboolean- Whether to find the work email address. Email enrichment is applied by default when no enrich flag is set. Example: true.
enrich_phone_numberboolean- Whether to find the mobile phone number. Requires the phone add-on on your BetterContact plan, otherwise the call is rejected with 402. Providing linkedin_url on each lead gives the best results. Example: false.
enrich_profileboolean- Whether to enrich the full LinkedIn profile such as headline, seniority, location, and current company. Every lead must include linkedin_url. Example: false.
timeout_secondsinteger- Maximum seconds the waterfall may run before the request is terminated with whatever has been found. Defaults to the timeout configured on your account when omitted. Example: 240.
verify_catch_allboolean- Whether to run the extra catch-all verification layer so email status is reported as catch_all_safe or catch_all_not_safe instead of catch_all. Requires the catch-all add-on on your plan, otherwise the call is rejected with 402. Example: false.
No tools match.
