llms.txt
Compare with other sites' llms.txt files →# MoltSets
> Go-to-market data platform built for AI agents. Valid business and personal emails, carrier-verified mobile phones, and SHA256 hashes for ad audiences, exposed as MCP- and REST-compatible APIs, plus Chrome and Firefox extensions for one-click LinkedIn lookups. MoltSets is open for sign-up.
MoltSets returns contact and company data an agent can act on directly. Differentiators that affect output quality:
- Every email carries its last-validation date (re-validated on a 90-day freshness window), plus an A-F risk score for send/don't-send decisions.
- Mobile numbers are carrier-validated in real time (mobiles only, no landlines).
- Multi-provider waterfalls maximise coverage on each call.
- One API covers business emails, personal emails, mobile phones, people and company search, reverse lookups, ad-audience identifiers (SHA256 and MAID), email-to-LinkedIn, and IP-to-company.
Base URL: `https://api.moltsets.com/api/v1/tools/`. Authentication: `Authorization: Bearer YOUR_API_KEY` on every request. Every request also needs a `User-Agent` header (any non-empty value). All requests are `POST` with a JSON body. Every call that completes returns HTTP 200 with the envelope `{ "results": {...}, "status": "ok" | "not_found", "metadata": {...} }`. Branch on `status`, not the HTTP code: `not_found` is a normal, uncharged miss (it still counts as one request). Errors return `4xx`/`5xx` with `{ "error": { "code": "...", "message": "..." } }`.
## Getting started
An agent can't sign up on its own. A human must first:
1. Create an account at https://app.moltsets.com.
2. Create credentials there, depending on how the agent will connect:
- For REST or the CLI: an API key (`ms_XXXXXXXXXXX`), created under API keys.
- For MCP: a Client ID and Client Secret, created under Connectors.
Choose a path:
- MCP (OAuth): for agents in chat and coding clients such as Claude, ChatGPT, Cursor and Claude Code. The client signs in once over OAuth and reads every tool, parameter and response schema from the server.
- REST (Bearer API key): for scripts, scheduled jobs, workflow tools (Clay, n8n) and your own product. Send the API key as a Bearer token on every request.
- CLI (API key): for agents with shell access, such as Claude Code and Codex, and for people working in a terminal. If the task involves a file or more than a handful of records, use the CLI; for one-off lookups in a chat client, use MCP.
MCP server URL: `https://mcp.moltsets.com/mcp`
MCP in a chat client (Claude.ai, ChatGPT): add `https://mcp.moltsets.com/mcp` as a custom connector, enter the Client ID and Client Secret under the connector's advanced settings, then sign in to MoltSets when prompted. ChatGPT needs Developer mode turned on before the custom connector option appears.
MCP in Claude Code:
```bash
claude mcp add --transport http moltsets https://mcp.moltsets.com/mcp \
--scope user \
--client-id YOUR_CLIENT_ID \
--client-secret
```
`--client-secret` takes no value: Claude Code prompts for it, then opens the MoltSets consent screen in the browser. Create the Client ID and Client Secret under Connectors at https://app.moltsets.com. MCP clients authenticate over OAuth; API keys (`ms_...`) are for REST calls.
Other MCP clients (Claude Desktop, Cursor, Windsurf, Grok and any client that supports remote HTTP servers): see https://developer.moltsets.com/integrations/moltsets-mcp.
REST example: find a business email from a name and company domain.
```bash
curl -X POST https://api.moltsets.com/api/v1/tools/search_business_email_by_name \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "User-Agent: YOUR_APP_NAME/1.0" \
-d '{"name": "John Smith", "company": "acme.com"}'
```
Response:
```json
{
"results": {
"email": "john.smith@acme.com",
"risk_score": "A",
"linkedin_url": "https://linkedin.com/in/john-smith-123"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
```
A miss returns the same envelope with `"status": "not_found"` and `null` values in `results`.
CLI: the MoltSets CLI (npm package `@moltsets/cli`; needs Node.js 18 or later) has one command per tool plus `enrich` for CSV files.
```bash
# Run without installing
npx moltsets --help
# Or install globally
npm install -g moltsets
```
- Auth: set the `MOLTSETS_API_KEY` environment variable. People can run `moltsets login` in an interactive terminal instead; agents and scripts should use the variable.
- Setup check: `moltsets whoami` (free) shows the plan, token balance and fair use headroom. Exit code 3 means no valid API key.
- Before a full enrich, always run `--dry-run` (no paid calls), then a small sample with `--limit 10`, then the whole file:
```bash
moltsets enrich leads.csv --tool linkedin_to_best_email --column linkedin --dry-run
moltsets enrich leads.csv --tool linkedin_to_best_email --column linkedin --limit 10 --out sample.csv
moltsets enrich leads.csv --tool linkedin_to_best_email --column linkedin --out enriched.csv
```
- Agent skill: `moltsets skill install` installs it to `~/.claude/skills/moltsets-cli/` (or `--dir <path>` for anywhere else).
## Key Pages
- [Homepage](https://moltsets.com/): Product overview and free signup.
- [AI agents](https://moltsets.com/how-it-works/agents/): Copy-paste setup prompt and one-click installs for Claude, ChatGPT, Cursor and other agents.
- [Pricing](https://moltsets.com/pricing/): Plans (Free, Solo, Pro, Team, Max) by rate limit, phone token add-on, and flat-file delivery.
- [How it works](https://moltsets.com/how-it-works/): Signup, API key, and connecting to Clay or Claude Code.
- [Integrations](https://moltsets.com/how-it-works/integrations/): Every place to use MoltSets - REST API, MCP clients (Claude, ChatGPT, Cursor, Windsurf, Grok), Chrome and Firefox extensions, Clay, Apify, Composio, Convertmax, Databar, Elaichi, Flowra, Oxygen, Outflare, Truto, Unified.to, EightOS and Dench - filterable by type, with billing (your plan or BYOK).
- [MCP server](https://moltsets.com/how-it-works/mcp-server/): Connecting Claude, ChatGPT, Cursor and other MCP clients to the MoltSets MCP server.
- [CLI](https://moltsets.com/how-it-works/cli/): Run every MoltSets tool from the terminal, enrich CSV files in bulk, and give coding agents like Claude Code and Codex a CLI with an agent skill.
- [REST API](https://moltsets.com/how-it-works/api/): Calling MoltSets over HTTPS from Clay, n8n, scripts or your own product.
- [MoltSets for LinkedIn Chrome extension](https://moltsets.com/how-it-works/linkedin-chrome-extension/): One-click LinkedIn profile enrichment, lead lists, and sends to HubSpot, Attio, Salesforce and Clay.
- [Our data](https://moltsets.com/our-data/): Every endpoint by category, the A-F email risk grades, and real-time mobile phone validation.
- [Affiliate Programme](https://moltsets.com/affiliate-programme/): Refer anyone who needs email addresses or phone numbers; 20% recurring commission, 60-day cookie, NET-30 payouts.
- [Brand guidelines](https://moltsets.com/brand-guidelines/): Brand guidelines and press kit: naming, wordmark and logomark downloads, colours, press contact.
- [Blog](https://moltsets.com/blog/): Guides, product updates, and go-to-market plays from the MoltSets team.
- [Terms of Service](https://moltsets.com/terms-of-service/)
- [Privacy Policy](https://moltsets.com/privacy-policy/)
- [Data Protection Addendum](https://moltsets.com/data-protection-addendum/)
- [Compliance](https://moltsets.com/compliance/)
- [Sub-processors List](https://moltsets.com/sub-processors-list/)
- [Frequently Asked Questions](https://moltsets.com/faq/)
## Resources
- [App](https://app.moltsets.com): Sign up, manage API keys, Connectors and billing.
- [Skills Library](https://moltsets.com/library/): Pre-built Claude Skills for identity resolution, contact enrichment, prospecting, IP intelligence, and more.
- [Skills Library index](https://moltsets.com/library/llms.txt): Full list of all skills with descriptions, categories, difficulty, and connections.
- [Help Desk](https://support.moltsets.com): Using the app, billing, and account management.
- [Developer Docs](https://developer.moltsets.com): API reference and MCP connection guides.
- [Full API reference (llms-full.txt)](https://developer.moltsets.com/llms-full.txt): The complete developer documentation and API reference in one plain-text file.
- [CLI on npm](https://www.npmjs.com/package/@moltsets/cli): The MoltSets CLI package, with the full command reference and exit codes.
- [CLI agent skill](https://unpkg.com/@moltsets/cli/skills/moltsets-cli/SKILL.md): The SKILL.md that `moltsets skill install` adds, teaching an agent when and how to use the CLI.
## Developer Documentation
- [Overview](https://developer.moltsets.com/getting-started/overview): What MoltSets is, base URL, request/response structure, plans, and available tools.
- [Authentication](https://developer.moltsets.com/getting-started/authentication): API key format (`ms_XXXXXXXXXXX`), creating and revoking keys, Bearer usage, OAuth for MCP clients, error responses.
- [Rate Limits](https://developer.moltsets.com/getting-started/rate-limits): Per-plan limits (shared by every key and connector on the account), concurrent search limits, phone token subscriptions, what counts as a request, 429 handling and `Retry-After`. Limits use rolling windows, not fixed daily resets: the first request opens a 5-hour window, everything in the next 5 hours draws from the same pool, and the next request after it closes opens a fresh one. The weekly window rolls the same way.
- [MoltSets App](https://developer.moltsets.com/getting-started/moltsets-app): Logging in and navigating the app.
- [Understanding Email Risk Scores](https://developer.moltsets.com/moltsets-data/email-risk-scores): Why third-party validators increasingly mislabel deliverable inboxes as invalid, and how the MoltSets Email Risk Score (A-F) gives a more accurate send/don't-send signal.
- [Understanding Phone Number Validation](https://developer.moltsets.com/moltsets-data/phone-number-validation): How MoltSets validates mobile numbers and how to weigh the `last_validated_at` date when deciding whether to use a number.
- [Understanding NAICS Codes](https://developer.moltsets.com/moltsets-data/understanding-naics-codes): What NAICS codes are, the 2-to-6-digit hierarchy, and how the `naics_code` filter on `search_companies` and `search_people` matches at any level. Includes all 20 sectors and their subsector tables.
- [Six-Digit NAICS Codes and Titles](https://developer.moltsets.com/moltsets-data/six-digit-naics-codes-titles): The complete six-digit NAICS national industry list (1,012 codes) organised by sector, the most specific level for the `naics_code` filter.
- [Searching for People](https://developer.moltsets.com/best-practices/searching-for-people): Building precise people searches, choosing the right filter, avoiding over-filtering on sparse fields, and paginating without burning records.
- [Searching for Companies](https://developer.moltsets.com/best-practices/searching-for-companies): Qualifying accounts, exact domain lookups, choosing an industry vocabulary, and the location caveat that trips up multinational targeting.
- [Getting Valid Emails](https://developer.moltsets.com/best-practices/getting-valid-emails): Which email endpoint to call, how to read the risk score before you send, and how to avoid paying for the same lookup twice.
- [Getting Carrier-Verified Mobile Phones](https://developer.moltsets.com/best-practices/getting-carrier-verified-mobile-phones): Appending verified mobile numbers, batching up to 100 profiles per call, budgeting phone tokens, and reading the validation date.
- [Finding Decision-Makers Across Companies](https://developer.moltsets.com/best-practices/finding-decision-makers-across-companies): Finding senior people at many companies with as few `search_people` calls as possible.
- [Getting Ad Audiences](https://developer.moltsets.com/best-practices/getting-ad-audiences): Turning contacts into privacy-safe advertising audiences, hashed email match keys for customer match, and MAIDs for mobile retargeting.
- [I Have X, I Want Y](https://developer.moltsets.com/use-cases/i-have-x-i-want-y): Tool selection by what data you have (email, HEM, LinkedIn, IP) and what you need. Covers email and people finding, identity resolution, company lookup, IP resolution, search, and chained workflows.
- [Find Companies and Contacts](https://developer.moltsets.com/use-cases/find-companies-and-contacts): Build prospect lists, look up companies by domain, and find contacts matching an ICP via the MCP or API. Covers filters, pagination, and code examples.
- [MoltSets MCP Server](https://developer.moltsets.com/integrations/moltsets-mcp): MCP server URL (`https://mcp.moltsets.com/mcp`), setup guides for Claude.ai, Claude Desktop, Claude Code, ChatGPT, Grok, Cursor, Windsurf and other MCP clients, reading outcomes, troubleshooting.
- [Clay HTTP API](https://developer.moltsets.com/integrations/clay): Use MoltSets tools in Clay via the HTTP API enrichment.
- [Chrome Extension](https://developer.moltsets.com/integrations/chrome-extension): MoltSets for LinkedIn side panel: one-click profile enrichment, lead lists, CSV export, and sends to HubSpot, Attio, Salesforce, Clay, Make, n8n, Zapier or any webhook.
- [Firefox Extension](https://developer.moltsets.com/integrations/firefox-extension): The same LinkedIn lookups in the Firefox sidebar.
## API Reference
### Search
- [POST /search_people](https://developer.moltsets.com/api-reference/search/search-for-people): Search people by title, seniority, department, company, industry, country, size, or revenue. Returns ranked business profiles with business email and risk score. Up to 25 records per call (`limit`, default 10); 10 records per call max on the Free plan. One query per call; page through results with `offset`.
- [POST /search_companies](https://developer.moltsets.com/api-reference/search/search-for-companies): Search companies by name, domain, industry, size, or revenue. Returns ranked company profiles. Up to 25 records per call (`limit`, default 10); 10 records per call max on the Free plan. One query per call; page through results with `offset`.
- [POST /search_linkedin_profile](https://developer.moltsets.com/api-reference/search/search-for-linkedin-profile): Search a person or company by name and company domain. Returns a LinkedIn slug. Use `count_only: true` (free) to check result volume before spending records or tokens. Single lookup only.
- [POST /search_business_email_by_name](https://developer.moltsets.com/api-reference/search/search-business-email-by-name): Name and company domain to valid business email plus matched LinkedIn URL. One-call shortcut for `search_linkedin_profile` plus `linkedin_to_business_email`. Charged only when found. Single lookup only.
- [POST /search_business_profile_by_name](https://developer.moltsets.com/api-reference/search/search-business-profile-by-name): [Advanced] Name and company domain to full business profile (company, title, firmographics). Single lookup only.
### Get Valid Emails
- [POST /linkedin_to_best_email](https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-best-email): LinkedIn URL to best available email (business preferred, falls back to personal). Returns a `type` field (`business` or `personal`). Batch up to 100 with `linkedin_urls`.
- [POST /linkedin_to_business_email](https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-business-email): LinkedIn URL to valid business email only. Batch up to 100 with `linkedin_urls`.
- [POST /linkedin_to_personal_email_usa](https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-personal-email-us-only): LinkedIn URL to valid personal email. US records only; on the Team and Max plans, capped at 15,000 personal email records per 5 hours and 75,000 per week (see Plans). Batch up to 100 with `linkedin_urls`.
- [POST /linkedin_to_best_personal_email_usa](https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-best-personal-email-us-only): LinkedIn URL to best personal email. US records only; on the Team and Max plans, capped at 15,000 personal email records per 5 hours and 75,000 per week (see Plans). Batch up to 100 with `linkedin_urls`.
### Get Carrier-Verified Mobile Phones
- [POST /linkedin_to_mobile_phone](https://developer.moltsets.com/api-reference/get-carrier-verified-mobile-phones/linkedin-to-mobile-phone): LinkedIn URL to verified mobile phone (mobiles only, no landlines). Spends 1 phone token per returned result; a miss costs nothing. Batch up to 100 with `linkedin_urls`.
### Reverse Lookups
- [POST /reverse_email_lookup](https://developer.moltsets.com/api-reference/reverse-lookups/reverse-email-lookup): Email to full business profile (name, title, seniority, company, LinkedIn, firmographics, emails on file). Batch up to 100 with `emails`.
- [POST /reverse_linkedin_lookup](https://developer.moltsets.com/api-reference/reverse-lookups/reverse-linkedin-lookup): LinkedIn URL to complete business profile (name, title, seniority, company, industry, revenue, business and personal email). Most complete LinkedIn enrichment. Single lookup only.
### Get Ad Audience
The ad-audience tools are not available on the Team or Max plans.
- [POST /email_to_maid](https://developer.moltsets.com/api-reference/get-ad-audience/email-to-maid): Email to mobile advertising IDs (MAIDs: AAIDs and IDFAs) for cross-device retargeting. Single lookup only.
- [POST /business_email_to_sha256](https://developer.moltsets.com/api-reference/get-ad-audience/business-email-to-sha256): Business email to SHA256 personal hashed emails for audience matching. Single lookup only.
- [POST /linkedin_to_sha256](https://developer.moltsets.com/api-reference/get-ad-audience/linkedin-to-sha256): LinkedIn URL to all known SHA256 hashes (business and personal). Single lookup only.
### Get LinkedIn
- [POST /email_to_linkedin](https://developer.moltsets.com/api-reference/get-linkedin/email-to-linkedin): Email to highest-confidence LinkedIn profile URL (scores all candidates, returns the best full URL). Single lookup only.
### Get Company
- [POST /ip_to_company](https://developer.moltsets.com/api-reference/get-company/ip-to-company): IPv4 address to company domain(s) behind the traffic. B2B web-visitor de-anonymisation. Single lookup only.
### Account
- [POST /get_account](https://developer.moltsets.com/api-reference/account/get-account): Account details, plan and status, token balance, `personal_email_available`, live Fair Use standing (`fair_use`), and phone token balance and subscription. Free.
- [POST /get_billing](https://developer.moltsets.com/api-reference/account/get-billing): Billing plan, renewal date, and the token cost of each tool (`token_costs`). Free.
- [POST /get_usage](https://developer.moltsets.com/api-reference/account/get-usage): Day-by-day usage for `today`, `week`, `month`, or `billing_cycle`, with totals for calls, with data, without data, and failed. Free.
## Errors
Every error uses one shape on REST and MCP: `{"error": {"code": "...", "message": "..."}}`. Branch on `error.code`. Nothing is charged on an error.
- `401 unauthorized`: missing, invalid or revoked API key.
- `403 forbidden`: missing `User-Agent` header. `403 account_inactive`: the account was cancelled. `403 plan_restricted`: the tool isn't on the account's plan (today, the ad-audience tools on the Team and Max plans); retrying or topping up won't clear it.
- `402 insufficient_tokens` / `insufficient_phone_tokens`: the token or phone token balance can't cover the call; a batch drops the items it can't cover and returns the rest.
- `404 tool_not_found