# Get Account
Source: https://developer.moltsets.com/api-reference/account/get-account
/openapi.json post /get_account
The Get Account API retrieves your MoltSets account details: account name, current plan, account status, remaining credit balance, number of API keys, and user count.
**Use this endpoint to:**
- Check account health programmatically
- Verify your account is active
- Display account information inside your own application or dashboard
# Get Billing
Source: https://developer.moltsets.com/api-reference/account/get-billing
/openapi.json post /get_billing
The Get Billing API retrieves your MoltSets billing details: current plan, subscription status, remaining credit balance, billing period start and end dates, and the credit cost for each available tool.
**Use this endpoint to:**
- Monitor spend against your plan
- Confirm your next renewal date
- Display live billing information inside your own application
# Get Usage
Source: https://developer.moltsets.com/api-reference/account/get-usage
/openapi.json post /get_usage
The Get Usage API retrieves a detailed breakdown of your MoltSets API credit usage for a chosen time period: today, the past week, the past month, or the current billing cycle.
It returns a day-by-day log of API calls made, credits consumed, successful lookups, empty results, and failed requests, along with period totals.
**Use this endpoint to:**
- Track consumption trends over time
- Audit usage day by day
- Build internal usage dashboards
# Business Email to SHA256
Source: https://developer.moltsets.com/api-reference/get-ad-audience/business-email-to-sha256
/openapi.json post /business_email_to_sha256
The Business Email to SHA256 API converts a business email address into SHA256-hashed personal email addresses, for privacy-safe identity resolution and paid advertising audience matching.
The hashes it returns can be uploaded directly to Meta, Google, LinkedIn, TikTok, and other ad platforms that support customer match or custom audience workflows. Use this to retarget known contacts across their personal devices without exposing raw personal email data.
**Use this endpoint to:**
- Build customer match audiences for Meta, Google, LinkedIn, or TikTok
- Retarget contacts on their personal devices without exposing raw email addresses
- Bridge business contacts to privacy-safe advertising identifiers
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Email to MAID
Source: https://developer.moltsets.com/api-reference/get-ad-audience/email-to-maid
/openapi.json post /email_to_maid
The Email to MAID API resolves an email address to one or more Mobile Advertising IDs (MAIDs), including AAIDs (Android Advertising IDs) and IDFAs (Apple Identifiers for Advertisers).
MAIDs are what ad platforms use to target users on their mobile devices with precision. Use this endpoint to connect a known email identity to mobile device signals, enabling cross-device retargeting, programmatic audience activation, and mobile-first ad campaigns against your contact lists.
**Use this endpoint to:**
- Build mobile retargeting audiences from your contact list
- Activate programmatic ad campaigns against known contacts
- Connect email identities to mobile device signals for cross-device targeting
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to SHA256
Source: https://developer.moltsets.com/api-reference/get-ad-audience/linkedin-to-sha256
/openapi.json post /linkedin_to_sha256
The LinkedIn to SHA256 API retrieves all known SHA256 and MD5 hashed emails for a LinkedIn profile, covering both business and personal addresses.
It returns separate arrays for business and personal hashes in both formats, giving you the broadest possible coverage for audience matching across ad platforms. Use this when you need to build the widest match key set for a LinkedIn-identified contact, for example to maximise match rates when uploading customer lists to Meta, Google, or LinkedIn Ads.
**Use this endpoint to:**
- Maximise match rates on ad platform customer lists
- Build a complete hashed identity set for one contact
- Bridge LinkedIn-sourced contacts into advertising audiences
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to Mobile Phone
Source: https://developer.moltsets.com/api-reference/get-carrier-verified-mobile-phones/linkedin-to-mobile-phone
/openapi.json post /linkedin_to_mobile_phone
The LinkedIn to Mobile Phone API looks up the carrier-verified mobile phone number for a LinkedIn profile, along with the date it was last verified.
Only mobile numbers are returned, no landlines or VoIP numbers, so every result is a real device. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`). Mobile lookups spend **phone tokens** — an allowance set by your plan, separate from your regular token balance — at 1 phone token per returned result.
**Numbers are not screened against Do Not Call registries.** MoltSets does not currently return DNC status, and a returned number carries no indication of whether it is registered. `last_validated_at` tells you the number was active and in service on that date, nothing more. Scrubbing against the applicable DNC registries, and complying with the calling and messaging rules that apply to you, remains your responsibility.
**Use this endpoint to:**
- Power SMS outreach and cold calling
- Enrich sales sequences with direct-dial mobile numbers
- Batch-append verified phone numbers to a contact list
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# IP to Company
Source: https://developer.moltsets.com/api-reference/get-company/ip-to-company
/openapi.json post /ip_to_company
The IP to Company API identifies the company associated with an IPv4 address.
Pass an IP address from your website visitor logs, server request data, or analytics platform, and get back the domain of the organisation behind that traffic. It's best suited to B2B use cases: consumer ISP addresses will typically not resolve to a named company.
**Use this endpoint to:**
- De-anonymise B2B website traffic
- Trigger account-based marketing and sales workflows
- Feed a website visitor identification pipeline
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Email to LinkedIn
Source: https://developer.moltsets.com/api-reference/get-linkedin/email-to-linkedin
/openapi.json post /email_to_linkedin
The Email to LinkedIn API resolves an email address to the highest-confidence LinkedIn profile URL when multiple candidates exist.
It scores all matching profiles and returns the single best full LinkedIn URL. Use this when match quality matters, for example before personalising outreach, triggering enrichment workflows, or appending LinkedIn data to a contact record.
**Use this endpoint to:**
- Attach the correct LinkedIn profile to an email-only contact
- Personalise outreach with accurate LinkedIn context
- Trigger downstream enrichment workflows from an email address
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to Best Email
Source: https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-best-email
/openapi.json post /linkedin_to_best_email
The LinkedIn to Email API finds the best available email address for any LinkedIn profile. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).
It returns a valid business email when one exists, and automatically falls back to a personal email if not, so you get a result whenever the data is available. The `type` field in the response tells you which kind was returned. Use this as your default LinkedIn-to-email enrichment endpoint when the type of email doesn't matter to you.
**Use this endpoint to:**
- Enrich LinkedIn-sourced leads with a working email address
- Maximise match rate across business and personal inboxes
- Fill contact records that only have a LinkedIn URL
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to Best Personal Email
Source: https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-best-personal-email
/openapi.json post /linkedin_to_best_personal_email
The LinkedIn to Best Personal Email API turns a LinkedIn profile into a valid personal email address in a single call. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).
Pass a LinkedIn URL or slug and get back the highest-confidence personal email MoltSets holds for that person, along with the date it was last validated. Cached validations are refreshed on a 90-day freshness window, so `last_validated_at` tells you exactly how fresh the check is. It can be `null` — a catch-all domain or a validation error leaves no date — so read `risk_score` alongside it.
**Use this endpoint to:**
- Get the single best personal email for a contact, with confidence
- Confirm an email is still active before sending
- Enrich records where deliverability matters most
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Plan Availability:**
This endpoint is not available on every plan. Access is set per account, not by price tier — call `get_account` and read `personal_email_available`. Where it is `false`, use `linkedin_to_business_email` instead, or contact support@moltsets.com to request access.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to Business Email
Source: https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-business-email
/openapi.json post /linkedin_to_business_email
The LinkedIn to Business Email API retrieves the valid work email address for any LinkedIn profile. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).
It only returns corporate email addresses, no personal inboxes. Use this when you need to reach contacts at their workplace domain, for example for B2B outreach, CRM enrichment, or account-based marketing campaigns. If you also want a personal email fallback, use `linkedin_to_best_email` instead.
**Use this endpoint to:**
- Reach prospects at their work email address
- Enrich B2B lead lists with corporate emails
- Power account-based marketing and sales sequences
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# LinkedIn to Personal Email
Source: https://developer.moltsets.com/api-reference/get-valid-emails/linkedin-to-personal-email
/openapi.json post /linkedin_to_personal_email
The LinkedIn to Personal Email API retrieves the valid personal email address, such as Gmail or iCloud, for any LinkedIn profile. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).
Use this to reach contacts outside their work inbox. It's well suited to recruitment outreach, consumer marketing, or re-engagement campaigns where a personal address improves deliverability.
**Use this endpoint to:**
- Reach candidates or prospects outside working hours
- Improve deliverability for consumer marketing sends
- Re-engage contacts who've left their previous employer
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Plan Availability:**
This endpoint is not available on every plan. Access is set per account, not by price tier — call `get_account` and read `personal_email_available`. Where it is `false`, use `linkedin_to_business_email` instead, or contact support@moltsets.com to request access.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Reverse Email Lookup
Source: https://developer.moltsets.com/api-reference/reverse-lookups/reverse-email-lookup
/openapi.json post /reverse_email_lookup
The Reverse Email Lookup API resolves an email address into a complete business profile, including full name, job title, seniority, company, LinkedIn URL, firmographic data, and any other email addresses on file.
**Use this endpoint to:**
- Enrich inbound leads and form fills with full contact context
- Qualify a prospect before you reach out
- Fill in missing profile data on an existing email list
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Reverse LinkedIn Lookup
Source: https://developer.moltsets.com/api-reference/reverse-lookups/reverse-linkedin-lookup
/openapi.json post /reverse_linkedin_lookup
The Reverse LinkedIn Lookup API resolves a LinkedIn profile URL into a complete business profile, including full name, job title, seniority, company name, company website, industry, revenue, a valid business email, and a personal email.
This is MoltSets' most complete LinkedIn enrichment endpoint. Use it when you need the full picture of a contact and their employer in a single call.
**Use this endpoint to:**
- Turn a LinkedIn URL into a fully enriched contact record
- Get company firmographics alongside personal contact details
- Power CRM enrichment workflows from a single input
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Enrichment.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Search Business Email by Name
Source: https://developer.moltsets.com/api-reference/search/search-business-email-by-name
/openapi.json post /search_business_email_by_name
The Business Email Finder API finds a person's valid work email address from just their name and company domain.
It runs a LinkedIn profile search and an email lookup in a single call, and returns the email address along with the matched LinkedIn profile URL. Pass a full name or separate `first_name` and `last_name` fields, and provide the company as a domain, for example `acme.com`. URLs are normalised automatically, and tokens are only charged when an email is found.
**Use this endpoint to:**
- Find a prospect's work email before outreach
- Fill in missing email fields on a lead list
- Enrich CRM records with verified contact emails
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Search.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Search Business Profile by Name
Source: https://developer.moltsets.com/api-reference/search/search-business-profile-by-name
/openapi.json post /search_business_profile_by_name
The Business Profile Finder API finds anyone's full business profile from just their name and company domain.
It runs a LinkedIn profile search and a firmographic lookup in a single call, and returns the person's job title and company, plus company details such as industry, size, and location. Pass a full name or separate `first_name` and `last_name` fields, and provide the company as a domain, for example `acme.com`. URLs are normalised automatically, and tokens are only charged when a match is found.
**Use this endpoint to:**
- Build a complete picture of a contact and their employer in one call
- Qualify leads with company context before outreach
- Enrich CRM records with job title and firmographic data
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Search.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Search for Companies
Source: https://developer.moltsets.com/api-reference/search/search-for-companies
/openapi.json post /search_companies
The Company Search API lets you search MoltSets' company database by name, domain, industry, employee count, or annual revenue, so you can find and qualify target accounts.
Use `query` for free text company name search, `domain` for an exact lookup by website domain, and the filters (`industry`, `employee_range`, `revenue_range`) to narrow your results. Combining `query` with filters gives the most precise matches. Every result comes back ranked, with a higher `_score` meaning a stronger match.
The `exclude_*` parameters (`exclude_domain`, `exclude_industry`, `exclude_employee_range`, `exclude_revenue_range`) work the other way round: each one takes a list and removes matches rather than selecting them. `exclude_domain` is how you suppress accounts you already have. Exclusions narrow a search but cannot be the whole search — you still need at least one positive input.
**Use this endpoint to:**
- Build prospect lists for account-based marketing
- Qualify target accounts before outreach
- Enrich CRM records with firmographic data
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Search.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Search for LinkedIn Profile
Source: https://developer.moltsets.com/api-reference/search/search-for-linkedin-profile
/openapi.json post /search_linkedin_profile
The LinkedIn Profile Search API finds a person or company's LinkedIn profile from a name and company domain.
Pass a full name (MoltSets splits it into first and last name for you) or send `first_name` and `last_name` separately, then add the company as a domain, for example `acme.com`. URLs are normalised automatically, so there's no need to clean up your inputs first.
Run a free count first with `count_only: true` to see how many matches exist, then tighten or loosen your search before spending tokens. Full results are only charged when a match is actually found, so an empty search costs nothing.
**Use this endpoint to:**
- Confirm you have the right LinkedIn profile before enriching a contact
- Check match volume before running a bulk search
- Attach LinkedIn URLs to contact records that are missing one
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Search.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Search for People
Source: https://developer.moltsets.com/api-reference/search/search-for-people
/openapi.json post /search_people
The People Search API lets you search MoltSets' contact database for people by name, job title, company, industry, country, seniority, or department.
Use `title` for the job title or role — it matches the title field alone, so it is far more precise than putting a role in `query`. Use `query` for the person's name, or for loose natural-language phrases when you have nothing more specific. To find people at a specific company, use `company` (company name) or `company_domain` (website domain) rather than putting the employer in `query`. Use the exact filters (`country`, `state`, `city`, `seniority`, `industry`, `department` or `functional_area`, `employee_range`, `revenue_range`) to narrow further — `employee_range` and `revenue_range` scope to people at companies of that size or revenue without needing a specific company. Combining `query` with filters gives the most precise matches. Every result comes back ranked, with a higher `_score` meaning a stronger match.
The `exclude_*` parameters (`exclude_company_domain`, `exclude_country`, `exclude_state`, `exclude_industry`, `exclude_seniority`, `exclude_employee_range`) work the other way round: each one takes a list and removes matches rather than selecting them. `exclude_company_domain` is how you suppress companies you already have. Exclusions narrow a search but cannot be the whole search — you still need at least one positive input.
**Use this endpoint to:**
- Build targeted lead lists for outbound sales
- Identify decision makers at specific target accounts
- Populate outbound sequences with verified contact data
**Fair Use Policy:**
This API is subject to our Fair Use Policy for Search.
**Outcomes:**
A lookup that finds nothing is not an error. It returns HTTP `200` with `status: "not_found"`, empty or null `results`, and the usual `metadata` — and costs no tokens, though it still counts as one request against your Fair Use requests limit. Read `status`, not the HTTP code, to tell a hit from a miss. The API's only `404` is an unknown or retired tool name.
# Getting Ad Audiences
Source: https://developer.moltsets.com/best-practices/getting-ad-audiences
How to turn MoltSets contacts into privacy-safe advertising audiences — hashed email match keys for customer match, and MAIDs for mobile retargeting.
Three endpoints convert a known contact into identifiers you can upload to ad platforms. All of them return **hashes or device IDs rather than raw personal emails**, which is what makes them usable in customer match and custom audience workflows.
## Choose the right endpoint
| You have | You want | Call |
| -------------- | -------------------------------------- | -------------------------- |
| LinkedIn URL | The widest possible set of match keys | `linkedin_to_sha256` |
| Business email | Hashed personal emails to match on | `business_email_to_sha256` |
| Any email | Mobile device IDs for in-app targeting | `email_to_maid` |
## Maximise match rate with `linkedin_to_sha256`
Match rate is the whole game with customer match uploads — a platform can only find the users whose identifiers you supply. `linkedin_to_sha256` returns the broadest set MoltSets holds for one person: **both address types, in both hash formats**.
```json theme={null}
{
"linkedin_slug": "john-smith-123",
"business_SHA256_array": ["..."],
"business_md5_array": ["..."],
"personal_SHA256_array": ["..."],
"personal_md5_array": ["..."]
}
```
Four arrays, not four values — a contact with several known addresses returns several hashes per array. Upload everything a platform accepts. Supplying both SHA256 and MD5 where supported, and both business and personal addresses, is the single biggest lever on match rate.
## Bridge work identities to personal devices
`business_email_to_sha256` takes a **business** email and returns **hashed personal** emails:
```json theme={null}
{ "personal_email_SHA256": ["..."] }
```
This is the endpoint that solves a specific B2B problem. Your CRM is full of work addresses, but people are logged into Meta, Google, and TikTok with their personal accounts — so uploading work emails to those platforms matches almost nothing. This crosses that gap without ever exposing a raw personal address.
## Reach devices with `email_to_maid`
`email_to_maid` resolves an email to one or more **Mobile Advertising IDs** — AAIDs on Android, IDFAs on Apple. These are the identifiers ad platforms use to target a specific device.
Use it for mobile retargeting, programmatic activation, and cross-device campaigns where you want to reach a known contact in-app rather than in an inbox.
## Where these go
The hashes returned by `business_email_to_sha256` and `linkedin_to_sha256` upload directly to any platform supporting customer match or custom audiences — **Meta, Google, LinkedIn, TikTok**, and others.
Check each platform's expected hash format before uploading. Most customer match products expect SHA256 of a normalised, lowercased email; a few still accept MD5. Supplying the format a platform doesn't expect is the most common reason a well-built audience matches at near zero.
## Build the audience, then activate it
The full path from an ICP to a live audience is a search followed by a hash lookup:
1. [`search_people`](/best-practices/searching-for-people) with your ICP filters → contacts with LinkedIn URLs
2. `linkedin_to_sha256` on each URL → hashed match keys
3. Upload to your ad platform as a customer match audience
Starting from a contact list you already own instead, `business_email_to_sha256` takes work emails straight to personal-address hashes in one step — no LinkedIn URL needed.
## Practical notes
* **Only pay for hits.** Tokens are charged only when data is found and returned. Contacts with no resolvable identifiers cost nothing — the call returns HTTP `200` with `status: "not_found"` and empty `results` — though the request still counts toward your rate limit.
* **Audiences decay.** People change devices and reset advertising IDs; MAIDs go stale faster than email hashes. Rebuild rather than reuse an old upload.
* **Mind platform minimums.** Most ad platforms won't activate an audience below a minimum size, and a list that matches thinly can fall under it. Check the top-level `total` on your source search before committing to the enrichment run — and note it stops counting at 10,000, so a `total` of `10000` means *at least* that many, not exactly that many.
## Related
Source the addresses that feed these audiences.
Build the ICP list to activate against.
# Getting Carrier-Verified Mobile Phones
Source: https://developer.moltsets.com/best-practices/getting-carrier-verified-mobile-phones
How to append verified mobile numbers with MoltSets — batching up to 100 profiles per call, budgeting phone tokens, and reading the validation date.
`linkedin_to_mobile_phone` is the only phone endpoint in the API. It takes a LinkedIn profile and returns a carrier-verified mobile number with the date it was last verified.
```json theme={null}
{
"mobile_phone": "+15551234567",
"last_validated_at": "2026-03-04"
}
```
## Mobile only, by design
Only mobile numbers are returned — **no landlines, no VoIP**. Every result is a real device, which is what makes the output usable for SMS and direct dial rather than a switchboard you have to navigate.
The practical consequence: contacts whose only number is a desk line simply won't return a result. A miss here isn't a data gap so much as a filter working as intended.
## Batch up to 100 per call
The endpoint takes either a single URL or a batch:
| Parameter | Type | Use |
| --------------- | ------ | --------------------------------------- |
| `linkedin_url` | string | One profile |
| `linkedin_urls` | array | Up to **100** profiles in a single call |
Batching is the single highest-leverage practice here. One call for 100 profiles instead of 100 calls cuts your request count by 99%, which matters because **every request counts toward your rate limit regardless of whether it returns data**.
```json theme={null}
{
"linkedin_urls": [
"https://linkedin.com/in/person-one",
"https://linkedin.com/in/person-two"
]
}
```
For lists longer than 100, chunk into batches of 100 and pause briefly between them rather than firing everything at once. See [Rate Limits](/getting-started/rate-limits) for the per-plan ceilings.
## Budget phone tokens first
Mobile lookups draw on **phone tokens**, an allowance set by your plan and separate from your regular token balance. One phone token is spent per returned result.
Phone tokens by plan:
| Plan | Phone tokens |
| ------------- | ------------ |
| \$0 | 10 |
| \$27 / month | 10 |
| \$97 / month | 50 |
| \$997 / month | 250 |
You're only charged for results that come back — profiles with no mobile on file cost nothing, and come back as HTTP `200` with `status: "not_found"` rather than an error. A batch of 100 profiles can therefore spend up to 100 phone tokens, more than the \$0, \$27, and \$97 allowances hold, so size batches to the allowance rather than to the endpoint's 100-profile ceiling.
`get_account` and `get_billing` are **free** and never cost tokens. Check your remaining allowance before a large run so a job doesn't stall halfway through.
## Qualify before you enrich
Because phone tokens are the scarcest thing on every plan, it pays to narrow the list before calling this endpoint rather than after. Run your [people search](/best-practices/searching-for-people) filters first and enrich only the contacts you'd actually call:
1. `search_people` with `seniority`, `department`, and location filters
2. Review the top-level `total` and tighten until the list is the size you intend to work (`total` stops counting at 10,000)
3. Batch the resulting LinkedIn URLs into `linkedin_to_mobile_phone`, up to 100 at a time and within your phone token allowance
Enriching a 5,000-row list "just in case" is how a phone token allowance disappears in one afternoon.
## Read the validation date
`last_validated_at` is the date the number was last confirmed active and in service.
Unlike email, MoltSets does **not** assign a risk score or confidence grade to phone numbers. The validation date is the signal — a number confirmed last week carries more confidence than one confirmed a year ago, and it's your call how much weight to give it. See [Understanding Phone Number Validation](/moltsets-data/phone-number-validation).
Set a staleness threshold that matches the channel. Cold calling a number verified 18 months ago wastes a dial; sending SMS to one wastes money and can generate complaints.
## Screen against DNC yourself
MoltSets does **not** currently provide Do Not Call status. No field in the response indicates whether a number is on a DNC registry, and a returned number is not a number that has been cleared to call.
`last_validated_at` confirms only that the number was active and in service on that date. It is not a permission signal. Scrubbing against the applicable DNC registries before you dial or send, and complying with the calling and messaging rules that apply to you, is your responsibility.
Practically, that means putting a DNC scrub between enrichment and outreach: take the numbers this endpoint returns, run them through your own registry check or your dialer's built-in scrubbing, and call only what survives. The endpoint fits the enrichment step of that pipeline, not the compliance step.
## Related
What the validation date does and doesn't tell you.
Batching, backoff, and per-plan ceilings.
# Getting Valid Emails
Source: https://developer.moltsets.com/best-practices/getting-valid-emails
Which MoltSets email endpoint to call, how to read the risk score before you send, and how to avoid paying for the same lookup twice.
MoltSets has five ways to get an email address. They differ in what you put in, what kind of address comes out, and whether you get a fallback. Picking the right one is mostly about what identifier you're starting from.
## Choose the right endpoint
| You have | You want | Call |
| --------------------- | ---------------------------------------------- | ------------------------------------ |
| LinkedIn URL | Any working address, don't care which kind | `linkedin_to_best_email` |
| LinkedIn URL | Work address only | `linkedin_to_business_email` |
| LinkedIn URL | Personal address only | `linkedin_to_personal_email` \* |
| LinkedIn URL | The single highest-confidence personal address | `linkedin_to_best_personal_email` \* |
| Name + company domain | Work address, no LinkedIn URL needed | `search_business_email_by_name` |
\* The two personal-only endpoints are **not available on every plan**. Access is set per account, not by price tier — call `get_account` and read `personal_email_available` to know where yours stands. Where it's `false`, use `linkedin_to_business_email` instead, or contact [support@moltsets.com](mailto:support@moltsets.com) to request access.
Calls from an account without access return **403** with:
```json theme={null}
{
"error": {
"code": "plan_restricted",
"message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
}
}
```
Contact [support@moltsets.com](mailto:support@moltsets.com) to request access.
**`linkedin_to_best_email`** is the sensible default. It returns a business email when one exists and **falls back to a personal email** when one doesn't, so it has the highest match rate of the four. The `type` field tells you which kind you got:
```json theme={null}
{
"email": "john.smith@example.com",
"risk_score": "A",
"type": "business",
"last_validated_at": "2026-03-04"
}
```
**`search_business_email_by_name`** runs a LinkedIn profile search and an email lookup in a single call, and returns the matched `linkedin_url` alongside the email. Use it when you have a name and a company domain but no LinkedIn URL — it saves you a lookup.
## Read the risk score before you send
Every email MoltSets returns carries a `risk_score` — a single-letter grade for **send safety**. It grades the mailbox, not the match: an `A` means the address is safe to send to, not that MoltSets is more certain it belongs to the person you looked up.
| Grade | Meaning | Action |
| ----- | --------------------------------------------------------------------------------------- | -------------- |
| **A** | Validated deliverable — confirmed at validation time | Send |
| **B** | Known engagement — a past open, click, or order, so a send reached the inbox | Probably send |
| **C** | Catch-all server — deliverability can't be determined | Your call |
| **D** | Hard negative — invalid, spam trap, abuse, or a complaint sighting in the last 6 months | **Don't send** |
| **F** | No signal either way | Your call |
When signals disagree the order is **D > A > B > C > F** — a hard negative outranks even a fresh deliverable verdict.
The single rule worth automating: **suppress `D` at the list level.** It's the fastest way to trip spam traps and damage sender reputation for an entire list, and it's the one grade where the answer never depends on your risk tolerance.
Segment `C` and `F` away from `A`/`B` rather than dropping them — they're unknown, not bad. Warm them at lower volume and suppress non-responders after one or two attempts.
For what the grade does and doesn't measure, how each one is earned, and why other validation vendors began returning more false "invalid" results in 2026, see [Understanding Email Risk Scores](/moltsets-data/email-risk-scores).
## Check the validation date
`last_validated_at` tells you when the address was last confirmed. Emails decay — people change jobs and close inboxes — so a grade from a recent check carries more weight than an old one.
MoltSets revalidates on a **90-day** freshness window — a cached validation older than that is re-checked on the next lookup, across every email endpoint. There is no shorter window on `linkedin_to_best_personal_email` or anywhere else.
`last_validated_at` can also come back `null`. A catch-all domain has no result to record, and a vendor error leaves the date unset — so treat a missing date as *unknown*, and read `risk_score` (`C` or `F` in those cases) rather than assuming a recent check.
## Don't pay for the same lookup twice
Two places already return emails with risk scores attached, and calling a dedicated email endpoint afterwards is redundant:
* **`search_people`** results include `business_email` and `business_email_risk_score`
* **`reverse_linkedin_lookup`** returns `business_email`, `personal_email`, and the full `personal_emails` array — each with its own risk score — in a single call
If you're already running a search or a reverse lookup, check what came back before enriching further.
Tokens are only charged when data is found and returned. A lookup that finds nothing costs nothing — though it still counts against your rate limit. A miss comes back as HTTP `200` with `status: "not_found"`, so branch your fallback chain on `status`, not on the HTTP code.
## Business or personal — pick by channel
The two address types aren't interchangeable, and the right one depends on what you're sending.
**Business** (`linkedin_to_business_email`) suits B2B outreach, CRM enrichment, and account-based campaigns — anywhere reaching someone in a work context is the point.
**Personal** (`linkedin_to_personal_email`, `linkedin_to_best_personal_email` — not available on every plan; see the note above) suits recruitment, consumer marketing, and re-engagement. It's also the only address that survives a job change, which makes it the better choice for contacts who may have left the employer you have on file.
## A note on token spend
You're only charged for verified data that is actually returned — a lookup that finds nothing costs nothing.
`get_account`, `get_billing`, and `get_usage` are free and never cost tokens. Check your balance before a large run so a job doesn't stall halfway through.
## Related
Per-grade sending practice and list hygiene.
Turn those emails into privacy-safe ad audiences.
# Searching for Companies
Source: https://developer.moltsets.com/best-practices/searching-for-companies
How to qualify accounts with MoltSets — exact domain lookups, choosing an industry vocabulary, and the location caveat that trips up multinational targeting.
`search_companies` is how you build and qualify an account list before you go looking for people at those accounts. It shares most of its vocabulary with [`search_people`](/best-practices/searching-for-people), so filters you learn here transfer directly.
## Probe with `limit: 1` before you pull a page
`search_companies` has no free dry run — `count_only` exists only on `search_linkedin_profile` — so run every new search once at `limit: 1` before you fetch it at volume.
```json theme={null}
{ "industry": "Information Technology", "employee_range": "51-200", "revenue_range": "$10M - $20M", "limit": 1 }
```
One record costs one search record against your fair use pool. The same query at `limit: 25`, walked five pages deep, costs 125 — and every filter here is exact-match, so a single wrong string spends all 125 on the wrong list. The usual culprits are all silent: a value that isn't in the enumeration at all, `"TX"` instead of `"Texas"`, a `linkedin_industry` label capitalised differently from the stored one, or a `country` filter pulling a multinational to the wrong office.
Read two things off the single result before you widen:
1. **`total`** — is the account universe the size you expected? A thin total means a filter value is off, not that the segment is empty. Try the neighbouring `industry` value or shorten the `naics_code`. `total` sits at the top level of the response, alongside `results` — not inside it. Over raw HTTP the body nests one level deeper, so the path is `results.total`.
2. **The record itself** — does this company actually match your intent? Check `domain`, `industry`, `employee_range`, and location against what you asked for.
Only then re-run with a real `limit` and start paginating.
Search records are capped separately from enrichment records and are consumed per record returned, on a rolling 5-hour window. This matters most when chaining — a `search_companies` result of 25 domains, each fanned out into a `search_people` call at `limit: 25`, is 625 search records from one loop. Probe **both** searches at `limit: 1` before running the chain. See [Rate Limits](/getting-started/rate-limits).
## Filters are free precision
Search cost is driven by the free-text `query`, not by the filters attached to it.
| Query shape | Speed and precision |
| ------------------------------- | -------------------------------- |
| `query` alone | Slower and less precise |
| `query` + any number of filters | Slower but **more precise** |
| Filters alone, no `query` | **Much faster and more precise** |
Two rules follow.
**Never send a bare `query`.** Adding `industry`, `employee_range`, or `revenue_range` costs nothing and sharply narrows the result set. A query-only call is the least precise shape available and no cheaper than a filtered one.
**Drop `query` entirely when filters can carry the whole intent.** Most account lists are pure firmographics — "software companies with 51–200 employees and $10M–$20M revenue" needs no free text at all, and runs much faster without it.
```json theme={null}
{ "industry": "Information Technology", "employee_range": "51-200", "revenue_range": "$10M - $20M" }
```
Reach for `query` only when you're matching a company by **name**. Everything else belongs in a filter.
This is about execution cost, not billing. Tokens are charged per record returned regardless of query shape — a cheaper query returns faster and puts less load on search capacity, but it doesn't change what you're charged.
## Use `domain` when you have one
If you know the website domain, `domain` is an exact match and always beats a free-text `query`:
```json theme={null}
{ "domain": "acme.com" }
```
Full URLs are **normalised automatically** — `https://www.acme.com/about` becomes `acme.com`. There's no need to strip the protocol or path first.
Reach for `query` only when you have a name and no domain. It searches the company name only; domain and industry are keyword fields and aren't covered by it.
## Choose your industry granularity
As with people search, three filters describe industry at different resolutions:
| Filter | Vocabulary | Use when |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `industry` | 22 fixed buckets | You're thinking in broad categories |
| `linkedin_industry` | LinkedIn's own vocabulary, hundreds of labels (\~85% filled) | You need a niche the buckets can't express |
| `naics_code` | Full NAICS hierarchy | You want standardised codes, or precise control over breadth |
The 22 `industry` buckets are the complete list — anything outside it matches nothing and returns zero results silently. Several niches have no bucket of their own: insurance carriers, aerospace and defence, mining, electronics, and biotech all fall inside broader buckets. When you need one of those specifically, use `linkedin_industry` instead — `"Insurance"`, `"Aerospace and Defense"`, `"Mining and Metals"` and hundreds more exist there as exact labels.
`naics_code` matches at any hierarchy level. Use a 2-digit sector (`"23"` = Construction) to cast wide, a 6-digit code (`"511210"` = Software Publishers) to go narrow. Shortening the code is the cleanest way to widen a search that's returning too little.
## Exclude what you don't want
Four filters remove companies instead of selecting them. Each takes a **list**, and each mirrors a filter you already know:
| Filter | Removes | Accepts |
| ------------------------ | ------------------ | ------------------------------------------------------------ |
| `exclude_domain` | Specific companies | Same values as `domain` — full URLs normalised automatically |
| `exclude_industry` | Whole industries | Same values as `industry` |
| `exclude_employee_range` | Headcount bands | Same values as `employee_range` |
| `exclude_revenue_range` | Revenue bands | Same values as `revenue_range` |
`exclude_domain` is your suppression list. Pass the accounts you already have — existing customers, current vendors, your own company — and they never appear:
```json theme={null}
{
"industry": "Information Technology",
"employee_range": "51-200",
"exclude_domain": ["acme.com", "stripe.com"]
}
```
The others carve out segments you don't sell to:
```json theme={null}
{
"industry": "Information Technology",
"exclude_employee_range": ["1-10", "11-20"],
"exclude_revenue_range": ["Below $500k"]
}
```
**Exclude in the query, not after it.** A company you exclude is never returned, so it costs you no tokens and no search records. Pulling 25 results and dropping five yourself costs you all 25.
Exclusions narrow a search — they can't be the whole search. At least one positive input (`query`, `domain`, or a regular filter) is still required.
`exclude_industry` only drops companies that **positively carry** one of the values you list. Companies with no industry on record aren't excluded by it, so they still come through. The same holds for the other exclusions — a missing value is not an excluded value.
## Understand the location caveat
`country` and `state` filter the company's location — but that location is **derived from where the company's team is based**.
This is accurate for the small companies that dominate the index, but **large multinationals are attributed to a single one of their offices**. A global company headquartered in one country may resolve to another entirely. When targeting large or international companies, combine location with other filters rather than relying on it alone.
Both require exact stored values with standard capitalisation — `"Texas"`, not `"TX"`. Combine `state` with `country` for precision.
Every company record comes back with a `city`, but there is no `city` filter on `search_companies` — `country` and `state` are the only location filters. To narrow to a city, filter on `state` and read `city` off the results. (`search_people` does have a `city` filter.)
## Watch the size and revenue distributions
Both range filters are exact-match, and both have a heavily skewed distribution.
**`employee_range`** — `"1-10"` is the most common value by a wide margin. A search filtered to small bands will return a great deal; one filtered to `"5001+"` will return very little.
| Value | Reads as |
| ------------- | -------------------------------------------- |
| `"1-10"` | Solo, micro, very small — most common by far |
| `"11-20"` | Tiny team |
| `"21-50"` | Small startup |
| `"51-200"` | Small-mid |
| `"201-500"` | Mid-size |
| `"501-1000"` | |
| `"1001-5000"` | Large |
| `"5001+"` | Enterprise, very large |
These eight bands are the complete list. Older documentation mentioned `"Small"`, `"Mid-Market"`, `"Enterprise"`, and `"Unknown"` — those are retired and now return nothing.
**`revenue_range`** — `"$500k - $1M"` is the most common band.
| Value | Reads as |
| --------------- | ----------------------- |
| `"Below $500k"` | Very small, pre-revenue |
| `"$500k - $1M"` | Most common band |
| `"$1M - $5M"` | |
| `"$5M - $10M"` | |
| `"$10M - $20M"` | Rare |
| `"$20M - $50M"` | |
| `"Above $50M"` | Everything larger |
`"Above $50M"` is a flat catch-all for **all** revenue over $50M — there is no finer band above it. Asking for $100M, $1B, or $5B companies means asking for `"Above $50M"` and narrowing with `employee_range`. Bands like `"$100M - $250M"` and `"Over $5B"` appeared in older documentation and are retired: they return nothing.
## Identify companies from traffic
`ip_to_company` resolves an IPv4 address to the domain of the organisation behind it — useful for de-anonymising website visitors and triggering account-based workflows.
```json theme={null}
{ "ip_address": "8.8.8.8" }
```
This is a B2B tool. Consumer ISP addresses will typically **not** resolve to a named company, so expect a meaningful miss rate on general web traffic.
## Chain company search into people search
The most common workflow is two calls: qualify accounts, then find contacts at them.
1. `search_companies` with your firmographic filters → gives you a list of domains
2. `search_people` with `company_domain` set to each domain → gives you contacts
```javascript theme={null}
const companies = await search("search_companies", {
industry: "Information Technology",
employee_range: "51-200",
revenue_range: "$10M - $20M",
limit: 25
});
for (const company of companies.results.results) {
const people = await search("search_people", {
company_domain: company.domain,
seniority: "VP",
limit: 25
});
}
```
Run the first iteration of that loop at `limit: 1` on both calls. A chain that looks right at one company per account is safe to fan out; one that isn't costs you the whole fan-out to find that out.
`search_people` can also filter on `employee_range` and `revenue_range` directly, applied to the person's current employer. If firmographics are the only reason you're calling `search_companies`, you can often skip it and filter in one call.
## Paginate deliberately
Results are ranked by `_score`, so the first page is the strongest.
| | Limit |
| --------------------------------- | ------------------ |
| Results per call | 25 max, 10 default |
| Results per call (Free plan) | 5 max |
| Free plan lifetime search records | 100 |
Read the top-level `total` before walking pages (`results.total` in the raw HTTP body), then increment `offset` by your `limit`. Every page you walk draws from the same search-record pool, so confirm the search is right at `limit: 1` before you commit to walking it.
**`total` stops counting at 10,000, and pagination stops there too.** A `total` of `10000` means *at least* 10,000 matches, not exactly 10,000 — don't size a run off it. `offset + limit` can't exceed 10,000 either, so no amount of paging reaches record 10,001. To pull a larger account list, split the search into narrower slices — by `country`, `state`, `employee_range`, or `revenue_range` — and walk each slice separately.
## Related
Find contacts at the accounts you've qualified.
Search records are capped separately from enrichment.
# Searching for People
Source: https://developer.moltsets.com/best-practices/searching-for-people
How to build precise people searches with MoltSets — choosing the right filter, avoiding over-filtering on sparse fields, and paginating without burning records.
`search_people` is the widest surface in the API: twenty-three parameters, most of them exact-match. The difference between a good search and a wasted one is almost always **which filter you reach for**, not how many you stack.
## Start with a free count
`search_linkedin_profile` accepts `count_only: true`, which returns the number of matching results **without fetching data or charging tokens**. Use it to size a search before committing to it.
```json theme={null}
{ "name": "John Smith", "company_domain": "acme.com", "count_only": true }
```
Tokens are only charged when data is found and returned. A search that matches nothing costs nothing — but it still counts against your rate limit. A zero-hit search is HTTP `200` with `status: "not_found"` and `total: 0`, not an error. See [Rate Limits](/getting-started/rate-limits).
## Probe with `limit: 1` before you pull a page
`count_only` is only available on `search_linkedin_profile`. On `search_people` there is no free dry run — so the cheapest way to check that a search is actually returning the people you meant is to run it with `limit: 1`.
```json theme={null}
{ "seniority": "VP", "department": "Sales", "industry": "Information Technology", "country": "United States", "limit": 1 }
```
One record costs one search record against your fair use pool. The same query at `limit: 25`, walked five pages deep, costs 125 — and if a filter value was misspelt, a `department`/`functional_area` pair contradicted itself, or `city` matched a suburb you didn't want, all 125 are spent on the wrong audience and can't be refunded.
Read three things off the single result before you widen:
1. **`total`** — is the audience the size you expected? A total of 0 or 3 means a filter is wrong, not that the market is empty. `total` sits at the top level of the response, alongside `results` — not inside it. Over raw HTTP the body nests one level deeper, so the path is `results.total`.
2. **The record itself** — does this person actually match your intent? Check `title`, `seniority`, location, and employer against what you asked for.
3. **`business_email` and `business_email_risk_score`** — if you're searching in order to email, confirm the emails are present and graded well enough to be worth pulling at volume.
Only when all three look right should you re-run with a larger `limit` and start paginating.
Search records are capped separately from enrichment records and are consumed per record returned, on a rolling 5-hour window. A single unchecked `limit: 25` loop can burn a meaningful share of a plan's pool before you notice the filters were wrong. See [Rate Limits](/getting-started/rate-limits).
## Filters are free precision
Search cost is driven by the free-text `query`, not by the filters attached to it.
| Query shape | Speed and precision |
| ------------------------------- | -------------------------------- |
| `query` alone | Slower and less precise |
| `query` + any number of filters | Slower but **more precise** |
| Filters alone, no `query` | **Much faster and more precise** |
Two rules follow.
**Never send a bare `query`.** Attaching `country`, `seniority`, or anything else costs nothing and sharply narrows the result set. A query-only call is the least precise shape available and no cheaper than a filtered one.
**Drop `query` entirely when filters can carry the whole intent.** "VPs of sales at US software companies" is fully expressible as `seniority`, `department`, `industry`, and `country` — as a pure filter search it runs much faster than the same request phrased as free text.
This is about execution cost, not billing. Tokens are charged per record returned regardless of query shape — a cheaper query returns faster and puts less load on search capacity, but it doesn't change what you're charged.
### If all you have is text, add a country
`country` is \~99% filled — the highest fill rate of any filter. Attaching it to a free-text search discards almost no legitimate matches while removing everything from other markets. It is the cheapest precision available, and the default filter to reach for when you have nothing else.
```json theme={null}
{ "title": "Account Executive", "country": "United States" }
```
## Put the right thing in `query`
`query` is a full-text search across `full_name`, `first_name`, `last_name`, company name, `title` (\~85% filled), and `headline` (\~65% filled). Multi-word queries distribute terms across fields — `"John Smith"` matches `first_name: John` **and** `last_name: Smith` rather than either alone.
| Put this in `query` | Use a dedicated filter instead |
| -------------------------------------------------------- | ----------------------------------------------------------------- |
| Names — `"Jane Doe"` | Job titles and roles — use `title` |
| Loose phrases with nothing better — `"recruiter London"` | Seniority level — use `seniority` |
| | A specific employer — use `company` or `company_domain` |
| | Country, state, city, industry, department, company size, revenue |
Naming a company in `query` gets it diluted across the name and title fields. Use `company` or `company_domain` to scope to an employer.
## Search roles with `title`, not `query`
`title` filters on the job title field alone, which makes it the precise way to search by role. A role dropped into `query` is spread across names, company names, and the headline, so it matches loosely — `query: "Account Executive"` will also bring back Account Managers.
```json theme={null}
{ "title": "Account Executive", "country": "United States" }
```
The match is analysed rather than literal, and how strict it is depends on the length of what you pass:
| Words you pass | Words that must match |
| -------------- | ---------------------------------------------------------------------- |
| One or two | **All of them** — `"Account Executive"` never returns Account Managers |
| Three or four | All but one |
| Five or six | All but two |
That allowance is what keeps function words from breaking a match: `"VP of Sales"` still finds someone stored as `"VP, Sales"`. Extra words in the **stored** title are always fine — `"Account Executive"` matches `"Senior Account Executive, SMB"`.
`title` and `seniority` answer different questions and combine well. Use `seniority` for the level, `title` for the role:
```json theme={null}
{ "title": "Sales", "seniority": "VP", "country": "United States" }
```
`title` is \~85% filled. The \~15% of profiles with no title on record can never match a `title` filter, no matter what you pass — so a title filter always trades some reach for its precision.
## Know each filter's fill rate
Every exact-match filter silently discards records where that field is empty. Stacking three sparse filters can cut a viable audience to nothing.
| Filter | Fill rate | Notes |
| -------------------------------- | --------- | ------------------------------------------------------- |
| `country` | \~99% | The most reliable filter available |
| `title` | \~85% | Profiles with no title can never match a `title` filter |
| `query` → `headline` | \~65% | |
| `seniority` | \~60% | |
| `industry` | \~60% | |
| `department` / `functional_area` | \~60% | Co-populated — use one or the other, never both |
| `naics_code` | \~50% | |
| `linkedin_industry` | \~85% | |
`department` and `functional_area` share the same underlying data, the same document counts, and the same values. Filtering on both narrows nothing and risks contradicting yourself — pick one.
## Choose your industry granularity
Three filters describe industry at different resolutions. Pick the one that matches how specific your targeting actually is.
| Filter | Vocabulary | Use when |
| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `industry` | 22 fixed buckets (\~60% filled) | You're thinking in categories like "software" or "healthcare" |
| `linkedin_industry` | LinkedIn's own vocabulary, hundreds of labels | You need a niche the broad buckets can't express — `"Wellness and Fitness Services"`, `"Staffing and Recruiting"` |
| `naics_code` | Full NAICS hierarchy | You need standardised codes, or want to control breadth precisely |
`naics_code` works at **any** level of the hierarchy. A 2-digit sector is broad (`"54"` = Professional Services); a 6-digit code is surgical (`"541120"` = Offices of Notaries). Shorten the code to widen the net.
## Get location right
`country`, `state`, and `city` all filter the **person's** location and all require exact stored values.
* Use full English names, not abbreviations — `"Texas"`, not `"TX"`.
* `"UK"` and `"HK"` exist in the data as dirty values. Prefer `"United Kingdom"` and `"Hong Kong"`.
* City names repeat across regions. Combine with `state` or `country` to disambiguate — `city: "Portland"`, `state: "Oregon"`.
* `city` matches the **exact stored city, not its suburbs**. For metro-area coverage, filter on `state` or `country` instead.
## Target by company size without naming a company
`employee_range` and `revenue_range` on `search_people` filter on the person's **current employer**. This finds people at companies of a given size or revenue without you having to supply a company at all.
```json theme={null}
{ "seniority": "VP", "employee_range": "51-200", "country": "United States" }
```
Both use the same vocabulary as `search_companies` — eight employee bands and seven revenue bands, and nothing else. Older documentation mentioned `"Small"`, `"Mid-Market"`, `"Enterprise"`, and `"Unknown"` for size, and finer revenue bands above `"Above $50M"`; those are retired and now return nothing.
## Exclude what you don't want
Six filters remove people instead of selecting them. Each takes a **list**, and each mirrors a filter you already know:
| Filter | Removes | Accepts |
| ------------------------ | ---------------------------- | -------------------------------------------------------------------- |
| `exclude_company_domain` | People at specific companies | Same values as `company_domain` — full URLs normalised automatically |
| `exclude_country` | Whole countries | Same values as `country` |
| `exclude_state` | States or regions | Same values as `state` |
| `exclude_industry` | Whole industries | Same values as `industry` |
| `exclude_seniority` | Seniority levels | Same values as `seniority` |
| `exclude_employee_range` | Employer size bands | Same values as `employee_range` |
`exclude_company_domain` is your suppression list — pass the accounts you already have and nobody from them appears:
```json theme={null}
{
"seniority": "VP",
"industry": "Information Technology",
"exclude_company_domain": ["acme.com", "stripe.com"]
}
```
The rest carve out segments. "US VPs, but not California, and no interns or entry-level":
```json theme={null}
{
"seniority": "VP",
"country": "United States",
"exclude_state": ["California"],
"exclude_seniority": ["Intern", "Entry"]
}
```
**Exclude in the query, not after it.** An excluded person is never returned, so they cost you no tokens and no search records. Pulling 25 results and discarding five yourself costs you all 25.
Exclusions narrow a search — they can't be the whole search. At least one positive input is still required.
Exclusion only drops profiles that **positively carry** the value you list. `industry` and `seniority` are each \~60% filled, so the \~40% of profiles with nothing on record are never excluded by `exclude_industry` or `exclude_seniority` — they still come through. A missing value is not an excluded value.
## Match exact strings exactly
Every non-`query` filter is an exact match. The most common failure is a near-miss on capitalisation or spacing:
* `"C Suite"` has a **space**, not a hyphen
* `"Marketing & Advertising"` uses an ampersand
* `"Medical & Health"` uses an ampersand
* `"5001+"` and `"$500k - $1M"` must match character for character
## Emails come back in the search
`search_people` results already include `business_email` and its `business_email_risk_score`. For contacts where the search returns an email, you don't need a follow-up enrichment call. See [Getting Valid Emails](/best-practices/getting-valid-emails) for what the grades mean.
## Paginate deliberately
Results are ranked — a higher `_score` means a stronger match, so the first page is the best page.
| | Limit |
| --------------------------------- | ------------------ |
| Results per call | 25 max, 10 default |
| Results per call (Free plan) | 5 max |
| Free plan lifetime search records | 100 |
Every response carries a top-level `total`, the count of matching records across all pages (`results.total` in the raw HTTP body). Read it **before** paginating to decide whether the search is worth walking, then increment `offset` by your `limit`. The `limit: 1` probe above gets you that total for the price of a single record.
**`total` stops counting at 10,000, and pagination stops there too.** A `total` of `10000` means *at least* 10,000 matches, not exactly 10,000 — don't size a run off it. `offset + limit` can't exceed 10,000 either, so no amount of paging reaches record 10,001. To pull a larger audience, split the search into narrower slices — by `state`, `industry`, `employee_range`, or `seniority` — and walk each slice separately.
## Related
Qualify accounts first, then find people at them.
Turn a contact into a deliverable address.
# Authentication
Source: https://developer.moltsets.com/getting-started/authentication
How to create and use API keys to authenticate requests.
MoltSets uses API key authentication. Every request must include your API key as a Bearer token in the `Authorization` header.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
API keys follow the format `ms_XXXXXXXXXXX`.
## Creating an API key
API keys are managed at [app.moltsets.com](https://app.moltsets.com/dashboard/api_keys).
1. To create an API Key, choose "create an API key"
2. Give it a name then click "create now"
Store your API key somewhere secure as soon as you create it!
## Using your API key
Pass the key as a Bearer token on every request:
```bash theme={null}
curl -X POST https://api.moltsets.com/api/v1/tools/get_account \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
## Multiple keys
You can create as many API keys as you need. The recommended pattern is one key per environment or agent — for example, separate keys for local development, staging, and production.
This makes it easy to revoke access for a specific environment without affecting others.
## Revoking a key
You can revoke credentials individually or all at once:
1. To revoke a single API Key or Connector, click **Revoke** to the right of the credential you want to remove.
2. To revoke all credentials at once, use the **Revoke All** option on the page.
Revocation is immediate and irreversible.
## OAuth — connecting an MCP client
MCP clients authenticate with an OAuth access token instead of a raw API key. Both credential types reach the same account and the same tools; use an API key for direct REST calls, and OAuth for anything connecting over the [MCP server](/integrations/moltsets-mcp).
Create the Client ID and Client Secret under **Connectors** at [app.moltsets.com](https://app.moltsets.com). Clients that support dynamic registration can register themselves instead.
| | |
| :------------------- | :----------------------------------------- |
| Authorization | `https://app.moltsets.com/oauth/authorize` |
| Token | `https://app.moltsets.com/oauth/token` |
| Dynamic registration | `https://app.moltsets.com/oauth/register` |
| Grant type | `authorization_code` |
| PKCE | `S256` |
| Scopes | `mcp`, `read`, `tokens` |
Metadata is discoverable at `https://mcp.moltsets.com/.well-known/oauth-protected-resource` and `https://app.moltsets.com/.well-known/oauth-authorization-server`.
### Redirect URIs
`https` is accepted on any host. Plain `http` is accepted **only** on a loopback host — `127.0.0.1`, `[::1]`, or `localhost` — which is what lets a CLI or desktop client complete the flow on an ephemeral local port, the native-app pattern from [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3). Every other host requires `https`.
For a registered loopback URI the **port may vary** between runs; scheme, host, path, and query must still match exactly. Non-loopback URIs are matched exactly, port included.
**PKCE is mandatory for loopback redirects** and is enforced at `/oauth/authorize`, before an authorization code exists. It remains optional for `https` redirect URIs.
A granted token is used the same way as an API key:
```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```
## Key permissions
All API keys have the same permissions — there are no read-only or scoped keys. Any key can call any tool on your account.
## Error responses
| Status | Code | Meaning |
| ------------------ | ------------------ | -------------------------------------------------------- |
| `401 Unauthorized` | `unauthorized` | Missing, invalid, or revoked API key |
| `403 Forbidden` | `account_inactive` | Valid key, but the account is not active |
| `403 Forbidden` | `plan_restricted` | Valid key, but the tool isn't part of the account's plan |
```json theme={null}
{
"error": {
"code": "unauthorized",
"message": "Invalid API key."
}
}
```
Every MoltSets error uses this shape — an `error` object with a `code` and a `message`. Branch on `code`; the message is for humans. The full list is in [Errors](/getting-started/overview#errors).
# MoltSets App
Source: https://developer.moltsets.com/getting-started/moltsets-app
## Logging in
[Logging in to MoltSets](https://app.moltsets.com) works the same way you signed up — no password required. Just make sure you use the same method you created your account with.
## Navigating the app
For more information on using the MoltSets app, visit our Help Desk at [https://support.moltsets.com](https://support.moltsets.com).
# Overview
Source: https://developer.moltsets.com/getting-started/overview
What MoltSets is, how it works, and where to start.
MoltSets is an identity resolution API. You give it a piece of data — an email address, LinkedIn URL, IP address, or hashed email — and it returns enriched contact and company information. Every tool follows the same request and response structure, so once you've made one call, you know how to make all of them.
## Base URL
All API requests go to:
```
https://api.moltsets.com/api/v1/tools/
```
Each tool has its own endpoint path. For example:
```
POST https://api.moltsets.com/api/v1/tools/linkedin_to_best_email
POST https://api.moltsets.com/api/v1/tools/ip_to_company
POST https://api.moltsets.com/api/v1/tools/get_account
```
## How a request works
Every request is a `POST` with a JSON body, an `Authorization` header, and a `Content-Type` header:
```bash theme={null}
curl -X POST https://api.moltsets.com/api/v1/tools/linkedin_to_best_email \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"linkedin_url": "https://linkedin.com/in/retentionadam"}'
```
## How a response works
Every call that completes returns HTTP `200` with a consistent envelope:
```json theme={null}
{
"results": { ... },
"status": "ok",
"metadata": {
"tokens_used": 1,
"tokens_remaining": 206
}
}
```
* **`results`** — the data returned by the tool. Empty, or with its fields set to `null`, when no data is found.
* **`status`** — `"ok"` when the tool found data, `"not_found"` when it completed but matched nothing.
* **`metadata.fair_use`** — your remaining record headroom in the 5-hour and 1-week windows, and when each resets.
* **`metadata.tokens_used`** — credits consumed. Always `0` when no data is returned. Sent on token-bound (free) accounts only — accounts on an unlimited plan omit it.
* **`metadata.tokens_remaining`** — your remaining credit balance after this request. Token-bound accounts only.
* **`metadata.personal_email_restricted`** — present and `true` only when the call withheld personal-email data because your plan doesn't include that surface. Read the missing field as a plan boundary, not as absent data.
`linkedin_to_mobile_phone` adds `phone_tokens_used` and `phone_tokens_remaining`; no other tool reports phone tokens.
**The HTTP status says whether the call completed. The body says what happened.** Branch on `status`, not on the HTTP code.
## Reading an outcome
Every call ends in one of three outcomes:
| Outcome | HTTP | Body | Cost |
| :------------ | :------------ | :--------------------------------------------------- | :-------------------- |
| **Found** | `200` | `status: "ok"` with populated `results` | Tokens charged |
| **Not found** | `200` | `status: "not_found"` with empty or `null` `results` | **No tokens charged** |
| **Error** | `4xx` / `5xx` | `error` object, no `results` | No tokens charged |
A not-found is a normal result, not a failure. The tool ran, the lookup was clean, and the data simply isn't on file for that input — so nothing is charged. It still counts as one request against your Fair Use requests limit.
```json theme={null}
{
"results": {
"email": null,
"type": null,
"last_validated_at": null
},
"status": "not_found",
"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"
}
}
}
```
Batches behave the same way. A batch returns `200` and its body is the per-item report — each entry carries its own `status`, so a batch of 100 where 12 matched returns 12 hits and 88 misses in one `200`. A batch where nothing matched is still `200` with `status: "not_found"`, not an error.
**This changed.** Lookups that found nothing used to return `404`. They now return `200` with `status: "not_found"`, on single calls and batches alike. If your integration treats a `404` as "no data", switch it to read `status` — the only `404` the API still returns is `tool_not_found`, meaning the tool name in the URL is unknown or retired.
### Reading the outcome without parsing the body
Every tool response also carries an **`X-MoltSets-Outcome`** header — `ok`, `not_found`, or the error code. Proxies, log pipelines, and clients that would rather not parse JSON can branch on it directly. It is absent on requests that ran no tool, such as an auth failure.
## Errors
Errors use a single shape on both REST and MCP:
```json theme={null}
{
"error": {
"code": "insufficient_tokens",
"message": "You have 0 tokens remaining."
}
}
```
Branch on `error.code`, not on the message text.
| Code | HTTP | What it means | What to do |
| :--------------------------- | :---- | :------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_input` | `422` | A parameter is missing, malformed, or outside its allowed values | Fix the parameter and retry. Retrying unchanged returns the same error |
| `unauthorized` | `401` | Missing, invalid, or revoked API key | Check the `Authorization` header, or issue a new key |
| `account_inactive` | `403` | The account is not active | Account is canceled either by choice or because of a payment issue. Login to your account to fix |
| `insufficient_tokens` | `402` | Token balance can't cover the call | Top up or upgrade. On a batch, unaffordable items are dropped and the rest still return |
| `insufficient_phone_tokens` | `402` | Phone-token allowance can't cover a mobile result | Phone tokens are a separate allowance — see [Rate Limits](/getting-started/rate-limits). Batches drop the excess rather than failing |
| `plan_restricted` | `403` | The tool isn't part of your plan — today, the dedicated personal-email tools | A plan condition: no `Retry-After`, and topping up tokens won't clear it. Use `linkedin_to_business_email`, or contact support |
| `fair_use_limit_exceeded` | `429` | A Fair Use **record** window is exhausted — or, on the free tier, the one-time search trial | Wait for `metadata.retry_after` seconds. Where the limit is the free search trial there is no `Retry-After`, because that grant never refreshes |
| `fair_use_requests_exceeded` | `429` | The 5-hour **request** window is exhausted | Wait for `metadata.retry_after` seconds, then resume |
| `rate_limited` | `429` | Burst guard — too many requests too quickly | Back off and retry; see [Handling rate limits](/getting-started/rate-limits#handling-rate-limits) |
| `tool_not_found` | `404` | The tool name in the URL is unknown or retired | Check the spelling against [Available tools](#available-tools). This is the API's only `404` |
| `internal_error` | `500` | The endpoint itself is temporarily unavailable | Not caused by your request. Requeue and retry later — see below |
Nothing is charged on an error.
## When an endpoint is offline
A `500` with `internal_error` means the endpoint itself is temporarily unavailable:
```json theme={null}
{
"error": {
"code": "internal_error",
"message": "Unexpected connection error."
},
"metadata": {}
}
```
Nothing about your request caused this — the API key, parameters, plan, and rate-limit headroom are all fine, and the same call will work again once the endpoint is back. **The MoltSets team is alerted automatically, so there's no need to report it.**
Resolution time varies, largely with when the outage starts: one that begins during office hours is picked up sooner than one overnight or over a weekend. Because of that, don't build a fixed retry delay around it — treat it as a transient failure in your pipeline, not a bad record, and requeue the affected calls to retry later instead of looping on the endpoint. A later call succeeding is the signal that the endpoint is back.
## Plans
| **Plan** | **Lifetime Tokens** | **Enrichment records** | **Search records** | **Phone Tokens** |
| :------------ | :------------------ | :---------------------- | :---------------------------- | :--------------- |
| \$0 | 1000 | 1k lifetime | 100 lifetime (5 per call max) | 10 lifetime |
| \$27 / month | Unlimited | 1k / 5h · 5k / week | 500 / 5h · 2.5k / week | 10 / month |
| \$97 / month | Unlimited | 15k / 5h · 75k / week | 7.5k / 5h · 37.5k / week | 50 / month |
| \$997 / month | Unlimited | 180k / 5h · 900k / week | 90k / 5h · 450k / week | 250 / month |
Records are the data rows returned; **requests** are capped separately — see [Rate Limits](/getting-started/rate-limits).
`linkedin_to_personal_email` and `linkedin_to_best_personal_email` are **not available on every plan** — access is set per account, not by price tier. Call `get_account` and read `personal_email_available` to know where yours stands.
Calls from an account without access return **403** with:
```json theme={null}
{
"error": {
"code": "plan_restricted",
"message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
}
}
```
Contact [support@moltsets.com](mailto:support@moltsets.com) to request access.
## Choosing a plan
The right plan depends on how fast you need results. Higher rate limits mean faster processing — the difference between waiting an hour and wrapping up in minutes.
| **Plan** | **Ideal for** |
| :------------ | :--------------------------------------------------------------- |
| \$0 | Exploring the API and testing integrations |
| \$27 / month | Low-volume agents or early production use |
| \$97 / month | Teams running identity resolution at scale |
| \$997 / month | High-throughput pipelines with sustained or unpredictable volume |
## More information
For more information on our plans, upgrading and downgrading processes, please refer to our support documentation at [support.moltsets.com](http://support.moltsets.com).
## Available tools
| Category | Tools |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Search** | `search_people`, `search_companies`, `search_linkedin_profile`, `search_business_email_by_name`, `search_business_profile_by_name` |
| **Get Valid Emails** | `linkedin_to_best_email`, `linkedin_to_business_email`, `linkedin_to_personal_email` \*, `linkedin_to_best_personal_email` \* |
| **Get Carrier-Verified Mobile Phones** | `linkedin_to_mobile_phone` |
| **Reverse Lookups** | `reverse_email_lookup`, `reverse_linkedin_lookup` |
| **Get Ad Audience** | `email_to_maid`, `business_email_to_sha256`, `linkedin_to_sha256` |
| **Get LinkedIn** | `email_to_linkedin` |
| **Get Company** | `ip_to_company` |
| **Account** | `get_account`, `get_billing`, `get_usage` |
\* `linkedin_to_personal_email` and `linkedin_to_best_personal_email` are **not available on every plan** — access is set per account, not by price tier. Call `get_account` and read `personal_email_available` to know where yours stands. See [Plans](#plans) for the error they return. Without access, use `linkedin_to_business_email` instead.
## What to do next
Get your API key and learn how to authenticate requests.
Understand the limits that apply to all plans.
# Rate Limits
Source: https://developer.moltsets.com/getting-started/rate-limits
Understand the request limits that apply to each MoltSets plan.
Rate limits vary by plan. All limits are per API key.
To prevent abuse, Unlimited Plans are subject to our [Fair Use Policy](https://moltsets.com/terms-of-service/).
## Enrichments
| **Plan** | **Enrichment records every 5 hours** | **Enrichment requests every 5 hours** | **Enrichment records per week** |
| :------------ | :----------------------------------- | :------------------------------------ | :------------------------------ |
| Free | 1k | 1k | 1k lifetime |
| \$27 / month | 1k | 5k | 5k |
| \$97 / month | 15k | 75k | 75k |
| \$997 / month | 180k | 900k | 900k |
## Searches
| **Plan** | **Search records every 5 hours** | **Search requests every 5 hours** | **Search records per week** |
| :------------ | :------------------------------- | :-------------------------------- | :-------------------------- |
| Free | 100 lifetime (5 per call max) | 100 lifetime | 100 lifetime |
| \$27 / month | 500 | 2.5k | 2.5k |
| \$97 / month | 7.5k | 37.5k | 37.5k |
| \$997 / month | 90k | 450k | 450k |
## How the window works
This works as a **rolling window, not a fixed daily reset**. The moment you make your first request, a 5-hour window opens. Everything you use for the next 5 hours draws from the same pool — the figure in your plan's row above. When the window closes, the limit resets, and your next request kicks off a fresh 5-hour window.
A \$97 account can therefore spend all 15k enrichment records in the first minute and then wait out the rest of that window, or spread the same 15k evenly across the five hours. The weekly window works the same way — it rolls from your first request rather than resetting on a calendar day.
Nothing is scheduled, so there's no reset hour to plan around. `get_account` reports `resets_at` for each window, which is the exact moment your current pool refills — see [Check where you stand](#check-where-you-stand).
## What counts as a request
Every API call counts toward the rate limit, regardless of whether it returns data — a `not_found` is still a request. Each item of a batch counts separately, so a batch of 100 counts as 100 requests. The free account tools (`get_account`, `get_billing`, `get_usage`) never count.
## What counts as a miss
A lookup that finds nothing still counts as a **request**, but consumes no **records** and no tokens. It returns HTTP `200` with `status: "not_found"` — see [Reading an outcome](/getting-started/overview#reading-an-outcome). Records are only consumed when data is actually returned, and are handed back if a later cap drops the result.
## Check where you stand
Before assuming you've hit a wall, check your current position. `get_account`, `get_billing`, and `get_usage` are **free** — they never cost tokens.
### `get_account` — live rate-limit standing
`get_account` returns a `fair_use` object that mirrors the tables above: `enrich` and `search`, each split into `records` and `requests`, over the `5h` and `1w` windows. Each window reports `limit`, `used`, `remaining`, and `resets_at` — so you can see exactly how much headroom is left and when the window rolls over.
```json theme={null}
"fair_use": {
"enrich": {
"records": { "5h": { "limit": 15000, "used": 0, "remaining": 15000, "resets_at": null } },
"requests": { "5h": { "limit": 75000, "used": 0, "remaining": 75000, "resets_at": null } }
},
"search": { "records": { "5h": { "limit": 7500, "used": 0, "remaining": 7500, "resets_at": null } } }
}
```
A `resets_at` of `null` means the window hasn't started counting yet (nothing used); once you make calls it carries the ISO 8601 timestamp when that window resets.
### `get_usage` — consumption history
`get_usage` shows how many calls you've actually made over a period, broken out by day plus a `totals` block — `calls`, `with_data`, `without_data`, and `failed`. Use it to spot bursts that are pushing you toward the 5-hour caps and to confirm which runs are driving your volume.
Ask your connected agent "check my MoltSets rate-limit headroom" and it will read these for you.
## Staying within the limit
A few approaches to keep your usage within bounds:
### Spread your automations out
If you're running scheduled tasks, split them across 2–4 runs per day rather than one large burst. Because the 5-hour window rolls from your first request, spacing runs at least five hours apart gives each one a fresh pool to draw from.
### Use batching with pauses between batches
For high-volume operations — say, updating 10,000 leads — don't fire all requests at once. Instead:
1. Group your calls into batches of 100
2. Wait 2 seconds between each batch
3. Continue until all requests are processed
If you need help adapting your code to work within these limits, any AI coding assistant can help restructure your logic.
## Rate limit errors
When you exceed a limit, the API returns `429 Too Many Requests` with one of three codes:
| Code | What ran out |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `fair_use_limit_exceeded` | A Fair Use **record** window — the records columns in the tables above. On the free tier, also the one-time search trial |
| `fair_use_requests_exceeded` | The 5-hour **request** window — every call attempted, hits and misses alike |
| `rate_limited` | The burst guard, which fires on too many requests in too short a time regardless of your plan headroom |
```json theme={null}
{
"error": {
"code": "fair_use_limit_exceeded",
"message": "Fair use record limit reached. Retry after the window resets."
},
"metadata": {
"retry_after": 7200
}
}
```
Fair Use `429`s carry `metadata.retry_after` — seconds until the binding window unlocks — and the same value in a `Retry-After` header. Wait that long rather than guessing a backoff.
The exception is a limit that is a plan condition rather than a window: an exhausted free-tier search trial returns `fair_use_limit_exceeded` with an upgrade message and **no** `Retry-After`, because that grant never refreshes. Retrying will not clear it.
The request is not retried automatically — your client is responsible for handling `429` responses.
### Batches return partial results, not a 429
When a batch runs past a Fair Use window, the items beyond your allowance are dropped unprocessed and the call still returns **`200`** with the results it did produce, plus an error block naming the cap that fired. That `200` carries `metadata.retry_after` and a `Retry-After` header, exactly like the single-call `429` — a half-succeeded batch is the response most likely to be retried in a tight loop, so read the header before resending. Resend only the items that were dropped.
## Handling rate limits
When a `429` carries `Retry-After`, honour it — it is the exact number of seconds until the binding window unlocks, and retrying sooner just burns request quota. Where there is no header, fall back to **exponential backoff**:
```javascript theme={null}
async function callWithBackoff(fn, retries = 4) {
for (let i = 0; i < retries; i++) {
try {
return await fn();
} catch (err) {
if (err.status !== 429 || i === retries - 1) throw err;
await new Promise(r => setTimeout(r, Math.pow(2, i) * 200));
}
}
}
```
**Batch endpoints** where available (e.g. `linkedin_to_mobile_phone` supports up to 100 `linkedin_urls` per call) let you reduce total request count significantly.
# Clay HTTP API
Source: https://developer.moltsets.com/integrations/clay
Use MoltSets tools directly in Clay via the HTTP API enrichment.
## Overview
Clay's HTTP API enrichment lets you call any REST API and map the response into your table. This guide walks through connecting any MoltSets tool to Clay.
## Prerequisites
* A MoltSets API key — see [Authentication](/getting-started/authentication) for how to create one
* A Clay table with a column containing the input data your chosen tool requires
## Setup
### 1. Add an HTTP API enrichment column
In your Clay table, click **+ Add column** and select **HTTP API**.
### 2. Configure the request
Set the following fields in the HTTP API configuration panel:
**Method**
```
POST
```
**Endpoint**
Enter the endpoint URL for the MoltSets tool you want to use. Find the correct URL on the tool's API reference page. Not sure which tool you need? See [I Have X, I Want Y](/use-cases/i-have-x-i-want-y).
**Headers**
| Key | Value |
| --------------- | --------------------- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer YOUR_API_KEY` |
Replace `YOUR_API_KEY` with your MoltSets API key.
**Body**
Enter the request body as shown in the tool's API reference page. For any fields that should pull from a Clay column, use Clay's `/` shortcut to insert a column reference in place of the value.
### 3. Configure the response
In the **Response values to return** field, enter:
```
results
```
This captures the entire `results` object from the MoltSets response into the HTTP API column.
### 4. Extract values into their own columns
Add a separate column for each value you want to extract from the response:
1. Click **+ Add column** and select **Formula**
2. Use `/` to reference the HTTP API column
3. Select the field you want from the field picker (e.g. `results.email`)
Repeat for each field you need.
Clay's HTTP API path traversal stops at one level deep, so entering `results.email` directly in the **Response values to return** field will not drill into the nested object. The two-column approach above is the expected workflow.
## Handling no results
When MoltSets finds no data for a given input, the call still succeeds: HTTP `200`, with `status` set to `"not_found"` and the fields in `results` empty or `null`. No tokens are charged.
In Clay, that means the row is not an error row — the HTTP API column fills in with a body like this:
```json theme={null}
{
"results": {
"email": null,
"risk_score": null
},
"status": "not_found",
"metadata": { ... }
}
```
Add a formula column on `status` if you want to split hits from misses — for example, only run a follow-up enrichment where `status` is `"ok"`. Filtering on the HTTP status code will not separate them, because both outcomes return `200`.
**This changed.** MoltSets used to return `404` when a lookup found nothing. Tables built to treat a `404` as "no data" should now read `status` instead. The only `404` left is an unknown or retired tool name in the URL.
***
## Related
* [Authentication](/getting-started/authentication) — create and manage API keys
* [API Reference Overview](/getting-started/overview) — all available tools and their endpoints
* [I Have X, I Want Y](/use-cases/i-have-x-i-want-y) — find the right tool based on your input data
* [MoltSets MCP](/integrations/moltsets-mcp) — use MoltSets directly in Claude Code or Claude.ai without HTTP setup
# MoltSets MCP Server
Source: https://developer.moltsets.com/integrations/moltsets-mcp
Connect Claude, Claude Code, and any MCP client to MoltSets. Give your AI agent live access to contact enrichment, HEM and IP resolution, and the full identity graph in one tool call.
> Legacy enrichment tools are form-based and manual. MoltSets is prompt-and-go. It's an MCP built specifically for AI agents — so your agent can de-anonymize website visitors, resolve hashed emails (HEMs) to real identities, enrich contacts from LinkedIn, and connect the dots between IP addresses, MAIDs, and people. The full identity graph, accessible in a single tool call.
## What is the MoltSets MCP Server?
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect directly to external tools and data sources instead of relying on their training data.
The **MoltSets MCP Server** gives any compatible AI tool direct access to MoltSets enrichment capabilities — every endpoint, parameter, and response schema — so your agent can enrich contacts, resolve identities, and look up visitor data without leaving the conversation.
**MCP Server URL**
```text theme={null}
https://mcp.moltsets.com/mcp
```
***
## Why Use It?
AI models are trained on static snapshots of the internet. When they generate code for an API, they often:
* Hallucinate endpoints that don't exist
* Use outdated parameter names
* Return incorrect response shapes
With the MoltSets MCP Server connected:
| Without MCP | With MCP |
| :------------------------- | :--------------------------------------- |
| AI guesses endpoint URLs | AI reads the real API reference |
| Outdated parameter names | Always up-to-date parameter schemas |
| Incorrect response shapes | Accurate response structures from source |
| Back-and-forth corrections | Correct code on the first try |
***
## Setup
How you add the connector depends on your account type. On a **personal** plan you add it yourself. On a **Team or Enterprise** plan, an Owner adds it once for the whole organization, then each member connects their own credentials.
1. In Claude.ai, go to **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Paste the following into **Remote MCP server URL**:
```text theme={null}
https://mcp.moltsets.com/mcp
```
4. Click **Advanced settings** and enter your MoltSets Connector credentials:
* **OAuth Client ID:** your Client ID
* **OAuth Client Secret:** your Client Secret
5. Click **Add**.
Free accounts are limited to a single custom connector. Pro and Max accounts can add multiple.
Only an **Owner or Primary Owner** can add a custom connector to a Team or Enterprise organization. Once added, each member connects to it individually — Claude only ever accesses data that the connecting member is authorized to see.
**Before you begin,** you will first need to invite your Owner or Primary Owner of your Claude Team/Enterprise account to MoltSets as they will need to have a MoltSets user in order to complete the connection process.
**Owner / Primary Owner — add the connector for the organization:**
1. Go to **Organization settings → Connectors**.
2. Click **Add**.
3. Hover over **Custom**, then select **Web**.
4. Paste the following into **Remote MCP server URL**:
```text theme={null}
https://mcp.moltsets.com/mcp
```
5. Click **Advanced settings** and enter the MoltSets Connector credentials (**OAuth Client ID** and **OAuth Client Secret**).
6. Click **Add**.
**Each member — connect to it:**
1. Go to **Customize → Connectors**.
2. Find the MoltSets connector (marked with a **Custom** label).
3. Click **Connect** and complete authentication.
To get your credentials, log into [app.moltsets.com](https://app.moltsets.com) and go to **Connectors** to create a new connector.
Claude Desktop shares the same connectors as your Claude account — no config file editing required, and a connector you add on Claude.ai is already available here. How you add it depends on your account type. On a **personal** plan you add it yourself. On a **Team or Enterprise** plan, an Owner adds it once for the whole organization, then each member connects their own credentials.
1. In Claude Desktop, go to **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Paste the following into **Remote MCP server URL**:
```text theme={null}
https://mcp.moltsets.com/mcp
```
4. Click **Advanced settings** and enter your MoltSets Connector credentials:
* **OAuth Client ID:** your Client ID
* **OAuth Client Secret:** your Client Secret
5. Click **Add**, then **restart Claude Desktop** so it picks up the connector.
Free accounts are limited to a single custom connector. Pro and Max accounts can add multiple.
Only an **Owner or Primary Owner** can add a custom connector to a Team or Enterprise organization. Once added, each member connects to it individually — Claude only ever accesses data that the connecting member is authorized to see.
**Owner / Primary Owner — add the connector for the organization:**
1. Go to **Organization settings → Connectors**.
2. Click **Add**.
3. Hover over **Custom**, then select **Web**.
4. Paste the following into **Remote MCP server URL**:
```text theme={null}
https://mcp.moltsets.com/mcp
```
5. Click **Advanced settings** and enter the MoltSets Connector credentials (**OAuth Client ID** and **OAuth Client Secret**).
6. Click **Add**.
**Each member — connect to it:**
1. In Claude Desktop, go to **Customize → Connectors**.
2. Find the MoltSets connector (marked with a **Custom** label).
3. Click **Connect** and complete authentication.
4. **Restart Claude Desktop** so it picks up the connector.
To get your credentials, log into [app.moltsets.com](https://app.moltsets.com) and go to **Connectors** to create a new connector.
### Configuring Tool Permissions
By default, all MoltSets tools are set to **Needs Approval** — Claude will prompt you the first time each tool is used. To update permissions in bulk:
1. Go to **Customize → Connectors**
2. Click **Configure** beside the MoltSets connector
3. Use the bulk change tool to set all tools to **Always Allow**
To restrict specific tools, set them individually to **Blocked**.
Run the following command in your terminal, replacing the placeholder values with your credentials:
```bash theme={null}
claude mcp add --transport http moltsets https://mcp.moltsets.com/mcp \
--client-id YOUR_CLIENT_ID \
--client-secret
```
The `--client-secret` flag takes no value — Claude Code prompts you for the secret (or reads it from the `MCP_CLIENT_SECRET` environment variable).
By default the server is added at the `local` scope (current project only). Add `--scope user` to make MoltSets available across all your projects:
```bash theme={null}
claude mcp add --transport http moltsets https://mcp.moltsets.com/mcp \
--scope user \
--client-id YOUR_CLIENT_ID \
--client-secret
```
Claude Code will open a browser window and prompt you to approve access on the MoltSets consent screen. Once approved, your token is stored and managed automatically.
**Personal account:** the command above works as-is.
**Team or Enterprise account:** on business plans, only admins can add MCP servers to Claude Code. If you sign into Claude Code with your Claude.ai account, any MoltSets connector already added there is available in Claude Code automatically — no `claude mcp add` needed.
Either way each seat authorizes over OAuth in the browser, so there's no need to distribute `ms_` API keys across an organization.
To get your credentials, log into [app.moltsets.com](https://app.moltsets.com) and go to **Connectors** to create a new connector.
Any MCP client that supports remote servers over HTTP can connect — CLI agents, desktop apps, and IDE extensions included.
1. Add `https://mcp.moltsets.com/mcp` as a remote MCP server in your client.
2. When the client asks for OAuth credentials, paste the **Client ID** and **Client Secret** from the **Connectors** page at [app.moltsets.com](https://app.moltsets.com). Clients that register themselves can skip this step.
3. Approve access on the MoltSets consent screen when the browser opens. The client stores the token from there; re-run the flow if it expires.
Clients that run in a terminal complete this on a local port — `http://127.0.0.1:/callback` and its `localhost` and `[::1]` equivalents are supported, so no HTTPS callback is needed on your machine.
Endpoints, scopes, and redirect URI rules are on the [Authentication](/getting-started/authentication#oauth--connecting-an-mcp-client) page, and are discoverable from the server itself at `https://mcp.moltsets.com/.well-known/oauth-protected-resource`.
***
## Example Prompts
Once connected, you can talk to MoltSets the same way you'd talk to a colleague. Here are a few prompts to get started:
**Enrich a contact from LinkedIn**
> "Enrich this LinkedIn profile and give me their business email and phone number: linkedin.com/in/example"
**Look up a visitor**
> "I have an IP address from a site visitor — 192.0.2.1 — can you tell me who this is?"
**Resolve a hashed email**
> "Resolve this HEM to a real identity and return the name and company: `abc123...`"
**Bulk enrich a list**
> "Here are 10 LinkedIn URLs. Enrich each one for business email and return the results as a table."
Visit "[**I Have X, I Want Y**](/use-cases/i-have-x-i-want-y)" for more example prompts.
***
## Reading an outcome
Every MoltSets tool call ends in one of three outcomes, and the agent should tell them apart before it reports back to you:
| Outcome | MCP response | What it means |
| :------------ | :-------------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Found** | `isError: false`, `status: "ok"` | Data was found and returned. Tokens charged. |
| **Not found** | `isError: false`, `status: "not_found"` | The tool ran fine; MoltSets holds no data for that input. **Nothing charged.** |
| **Error** | `isError: true` with an error `code` | The call did not complete — bad input, no tokens, plan restriction, rate limit, or an outage. |
**A not-found is a normal, uncharged result — not a failure.** The lookup was clean, the data simply isn't on file for that input. It still consumes one request against your Fair Use requests limit. An agent should say "no email on file for that profile" and move on — or try a neighbouring tool — rather than reporting that the API errored.
Where to go next after a miss:
| Missed on | Try next |
| :------------------------------ | :----------------------------------------------------------------------------------- |
| `linkedin_to_business_email` | `linkedin_to_best_email`, then `linkedin_to_personal_email` (where your plan allows) |
| `linkedin_to_best_email` | `reverse_linkedin_lookup` for the wider profile |
| `search_business_email_by_name` | `search_linkedin_profile` to confirm the person exists, then enrich |
| `email_to_linkedin` | `reverse_email_lookup` for the profile without the URL |
| `ip_to_company` | Nothing — consumer ISP traffic often has no company behind it |
### When it really is an error
A genuine error comes back with `isError: true` and an `error.code`. What the agent should do next depends on the code:
| Code | Means | Next step |
| :------------------------------------------------------- | :---------------------------------- | :------------------------------------------------------------------ |
| `invalid_input` | A parameter is wrong | Fix the parameter — rerunning it unchanged repeats the error |
| `insufficient_tokens` | Out of tokens | Top up or upgrade; `get_billing` shows the balance |
| `insufficient_phone_tokens` | Out of phone tokens | A separate allowance from regular tokens |
| `plan_restricted` | The tool isn't on your plan | A plan condition, not a data miss — switch tools or contact support |
| `fair_use_limit_exceeded` / `fair_use_requests_exceeded` | A Fair Use window is exhausted | Wait `metadata.retry_after` seconds, then resume |
| `rate_limited` | Too many calls too quickly | Back off briefly |
| `unauthorized` / `account_inactive` | Credentials or account problem | Recheck the connector; contact support if the account is inactive |
| `tool_not_found` | Unknown or retired tool name | Check the name against `tools/list` |
| `internal_error` | The endpoint is temporarily offline | Stop retrying that tool, do something else, come back later |
Nothing is charged on an error. The full table with REST status codes is in [Errors](/getting-started/overview#errors).
Over REST the same three outcomes map to HTTP status this way: found and not-found are both `200` (read `status` in the body to tell them apart), and errors are `4xx`/`5xx`. See [Reading an outcome](/getting-started/overview#reading-an-outcome).
***
## Tokens & Costs
You only spend tokens on **verified data that is actually returned**. A few rules the agent follows automatically:
* **No data, no charge.** Calls that come back with `status: "not_found"` cost nothing — a miss is a normal outcome, not an error.
* **Counting is free.** `search_linkedin_profile` with `count_only: true` returns match counts without spending tokens — use it to size a search before committing.
* **Free tools.** `get_account`, `get_billing`, and `get_usage` never cost tokens. Call `get_billing` for the per-tool `token_costs` map and your current balance.
* **Phone tokens are separate.** `linkedin_to_mobile_phone` spends **phone tokens** — an allowance set by your plan, separate from your regular token balance — at 1 phone token per returned result.
For a full breakdown, see the [Rate Limits](/getting-started/rate-limits) guide.
New to the API? Start with [Authentication](/getting-started/authentication) to create your keys, then browse the [API Reference Overview](/getting-started/overview) for every endpoint, parameter, and response schema the MCP exposes.
***
## Troubleshooting
Restart your AI tool after adding the MCP configuration. Most clients need a full restart to detect new MCP servers.
Verify the URL is exactly:
```text theme={null}
https://mcp.moltsets.com/mcp
```
No trailing slash, no extra path segments.
Terminal clients must call back to a loopback address — `127.0.0.1`, `localhost`, or `[::1]`. A plain `http` callback on any other host is refused; everything else must use `https`.
If your callback is loopback and it is still refused, check that the client sends a PKCE `code_challenge` (method `S256`) — it is required for loopback — and that the callback path matches the one registered for your connector. The port is allowed to change between runs; the path is not.
Full rules are on the [Authentication](/getting-started/authentication#redirect-uris) page.
Double-check that your Client ID and Client Secret are copied correctly from [app.moltsets.com](https://app.moltsets.com) — no extra spaces, no truncation.
If your credentials were recently rotated or revoked, generate a new connector from the **Connectors** page and update your config with the new values. Then restart your AI tool.
Check your network connection and try again. If the issue persists, verify the server is reachable by opening `https://mcp.moltsets.com/mcp` in your browser. If you see a response (even an error page), the server is up and the issue is likely local to your config.
A `500` with `internal_error` means the endpoint itself is temporarily offline:
```json theme={null}
{
"error": {
"code": "internal_error",
"message": "Unexpected connection error."
},
"metadata": {}
}
```
Nothing about the call caused it — credentials, parameters, and plan are all fine. **The MoltSets team is alerted automatically, so there's no need to report it.**
Resolution time varies with when the outage starts — an outage during office hours is picked up sooner than one overnight or over a weekend — so there's no useful fixed wait. Have your agent stop retrying that tool, work on something else, and come back to it later in the session or in a follow-up run.
`linkedin_to_personal_email` and `linkedin_to_best_personal_email` are **not available on every plan** — access is set per account, not by price tier. Call `get_account` and read `personal_email_available` to know where yours stands. Calls from an account without access return **403**:
```json theme={null}
{
"error": {
"code": "plan_restricted",
"message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
}
}
```
This is an account entitlement, not a data miss — retrying or rewording the prompt won't help. Use `linkedin_to_business_email` instead, or contact [support@moltsets.com](mailto:support@moltsets.com) to request access.
Check the `status` field on the response. A clean miss comes back as a **success** — `isError: false` with `status: "not_found"` — and costs nothing. It is not an error, and retrying the same input will return the same miss.
Older integrations saw a `404` for this case. That is no longer sent: over REST both a hit and a miss return `200`, and the body's `status` tells them apart. If an agent is relaying misses as API failures, tell it to read `status` before reporting, and to try the next tool in the [chain above](#reading-an-outcome).
# Understanding Email Risk Scores
Source: https://developer.moltsets.com/moltsets-data/email-risk-scores
What the A–F Email Risk Score measures — send safety, not identity accuracy — how each grade is earned, and how to act on it.
The Email Risk Score is a **send-safety grade**. It answers one question: *if you send to this address, how likely is it to land in an inbox rather than bounce, hit a spam trap, or damage your sending reputation?*
It is **not** a confidence score for whether the address belongs to the person you looked up.
**The most common misreading.** An `A` does not mean "we are certain this is their address." It means the mailbox is live and safe to send to. A `C` or `F` does not mean the match is wrong — it means we can't confirm deliverability. Grade the send, not the identity.
## What the score does and doesn't measure
| The score tells you | The score does not tell you |
| :---------------------------------------------------------------------------------- | :--------------------------------------------------------- |
| Whether the mailbox exists and accepts mail | Whether the address belongs to the person you searched for |
| Whether a past send to it landed without bouncing | Whether the person still works at that company |
| Whether the address has been seen as a spam trap or complaint source | How current the underlying record is |
| Whether the domain accepts everything (catch-all), making deliverability unknowable | How the address was sourced or derived |
Identity accuracy comes from the tool you called, not from this field. `search_business_email_by_name`, for example, matched a name against a company domain; the risk score then grades the resulting address for sending. The two are independent — a correctly matched address can be catch-all (`C`), and a deliverable address (`A`) can belong to a person who has since changed jobs. Read `last_validated_at` alongside the grade for freshness.
## Why the grade exists
In spring 2026, Microsoft began blocking SMTP-based validation checks. Third-party validators (NeverBounce, ZeroBounce, and others) consequently started marking fully configured, deliverable inboxes as "invalid" — addresses that receive mail perfectly well. A single vendor verdict is no longer a reliable send/don't-send signal.
The Email Risk Score is computed from everything MoltSets holds about the address — live validation, its own validation history, real engagement, and spam sightings — rather than from one SMTP probe.
## The grades
| Score | What it means | How it's earned | Recommendation |
| :---- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | :------------- |
| **A** | Validated deliverable | Confirmed `valid` at validation time, or a prior validation whose deliverable flag holds | Send |
| **B** | Known engagement, deliverability not re-validated | A recorded open, click, or order — proof a past send reached the inbox without bouncing | Probably send |
| **C** | Catch-all — deliverability unknowable | The receiving server accepts mail for every address at that domain, so acceptance proves nothing | Your call |
| **D** | Hard negative | A standing invalid, spam-trap, abuse, or do-not-mail verdict, or a spam/complaint sighting in the last 6 months | Don't send |
| **F** | No signal | No validation record and no engagement history — nothing is known either way | Your call |
Two points that trip people up:
* **`F` is not a bad grade, and `D` is not a strong one.** `F` means *no evidence*; `D` means *negative evidence*. They are opposite ends of what we know, not neighbouring tiers.
* **`C` is a property of the domain, not the person.** A catch-all server accepts everything, so no validator — ours or anyone else's — can confirm an individual mailbox behind it.
**Precedence** when signals disagree: **D > A > B > C > F**. A hard negative outranks everything, including a fresh deliverable verdict. A live catch-all verdict outranks older date-based evidence, because the server-level unknowable is the more current fact.
## How it reaches you
The grade is appended to every email a tool returns, next to the validation date:
```json theme={null}
{
"results": {
"email": "john.smith@example.com",
"risk_score": "A",
"last_validated_at": "2026-08-25"
},
"status": "ok"
}
```
Tools that return more than one address carry a companion field per address — `business_email_risk_score`, `personal_email_risk_score`, and a `personal_emails_risk_score` array index-aligned with `personal_emails`. `reverse_email_lookup` keeps its own field names. `search_people` rows carry `business_email_risk_score` alongside each contact.
Addresses that fail validation outright are **dropped before they reach you** rather than returned with a low grade — which is why most payloads skew toward `A`, `B`, and `C`. A lookup whose only address was dropped comes back as a `not_found`, and costs nothing.
Scoring is best-effort and never fails a call: if a scoring lookup is degraded, the `risk_score` field is simply absent. Treat a missing grade like `F` — unknown, not safe.
## Best practices
Treat the grade as a filter, not a guarantee. A "Send" recommendation lowers risk; it doesn't eliminate it. Pair it with your own domain reputation and list hygiene.
### By grade
| Grade | Best practice |
| :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A** | Safe to send immediately. Strongest deliverability signal available. |
| **B** | Solid for regular sends. For reputation-sensitive campaigns (cold outreach on a new domain), send a smaller batch before scaling. |
| **C** | Deliverability can't be confirmed. Segment separately from A/B, warm with lower volume, watch engagement closely, and suppress non-responders after 1–2 attempts. |
| **D** | Never send. The fastest way to trip spam traps and damage sender reputation for the whole list. |
| **F** | Unknown risk, not safe. Re-verify before sending, or route into the same cautious treatment as C. |
### General sending hygiene
* Suppress `D` at the list level automatically rather than relying on manual review
* Monitor bounce rate by grade over time to confirm the scoring holds up for your use case
* Warm up new domains regardless of grade when sending cold outreach
* Re-score periodically. Deliverability decays — job changes, inbox closures — and the grade reflects what was known at the time of the call, which `last_validated_at` dates for you
## Related
Which email endpoint to call, and how to avoid paying twice.
The phone-side equivalent, and how to read its validation date.
# Understanding Phone Number Validation
Source: https://developer.moltsets.com/moltsets-data/phone-number-validation
How MoltSets validates phone numbers and what the last validated date tells you.
## What we return
For phone numbers, MoltSets provides a **last validated date**. This tells you when the number was last confirmed to be active and in service.
## What this means for you
Unlike email, we don't currently assign a risk score or confidence rating to phone numbers. The last validated date is the signal we give you, and it's up to you to decide how much weight to put on it — for example, a number validated last week carries more confidence than one validated a year ago.
We also don't currently provide **Do Not Call (DNC) status**. No field in the payload tells you whether a number is on a DNC registry, and the last validated date says nothing about it either — a number can be active, in service, and registered on DNC all at once. Screening against the applicable registries before you call or message, and complying with the rules that apply to you, is on your side.
## How it works
The last validated date is appended to each phone number in the API payload.
# Six-Digit NAICS Codes & Titles
Source: https://developer.moltsets.com/moltsets-data/six-digit-naics-codes-titles
The complete six-digit NAICS national industry list, organized by two-digit sector — the most specific level available for the naics_code filter.
This is the full six-digit national industry list — the most specific level of the NAICS hierarchy. Use these codes with the `naics_code` filter on [`search_companies`](/best-practices/searching-for-companies) and [`search_people`](/best-practices/searching-for-people) to target a precise industry.
A six-digit code matches one exact industry. For broader targeting, shorten the code — a 2-digit sector or 3-digit subsector casts a wider net. See [Understanding NAICS Codes](/moltsets-data/understanding-naics-codes) for the sector and subsector reference.
## 11 — Agriculture, Forestry, Fishing and Hunting
| NAICS Code | Industry Title |
| ---------- | --------------------------------------------------- |
| 111110 | Soybean Farming |
| 111120 | Oilseed (except Soybean) Farming |
| 111130 | Dry Pea and Bean Farming |
| 111140 | Wheat Farming |
| 111150 | Corn Farming |
| 111160 | Rice Farming |
| 111191 | Oilseed and Grain Combination Farming |
| 111199 | All Other Grain Farming |
| 111211 | Potato Farming |
| 111219 | Other Vegetable (except Potato) and Melon Farming |
| 111310 | Orange Groves |
| 111320 | Citrus (except Orange) Groves |
| 111331 | Apple Orchards |
| 111332 | Grape Vineyards |
| 111333 | Strawberry Farming |
| 111334 | Berry (except Strawberry) Farming |
| 111335 | Tree Nut Farming |
| 111336 | Fruit and Tree Nut Combination Farming |
| 111339 | Other Noncitrus Fruit Farming |
| 111411 | Mushroom Production |
| 111419 | Other Food Crops Grown Under Cover |
| 111421 | Nursery and Tree Production |
| 111422 | Floriculture Production |
| 111910 | Tobacco Farming |
| 111920 | Cotton Farming |
| 111930 | Sugarcane Farming |
| 111940 | Hay Farming |
| 111991 | Sugar Beet Farming |
| 111992 | Peanut Farming |
| 111998 | All Other Miscellaneous Crop Farming |
| 112111 | Beef Cattle Ranching and Farming |
| 112112 | Cattle Feedlots |
| 112120 | Dairy Cattle and Milk Production |
| 112130 | Dual-Purpose Cattle Ranching and Farming |
| 112210 | Hog and Pig Farming |
| 112310 | Chicken Egg Production |
| 112320 | Broilers and Other Meat Type Chicken Production |
| 112330 | Turkey Production |
| 112340 | Poultry Hatcheries |
| 112390 | Other Poultry Production |
| 112410 | Sheep Farming |
| 112420 | Goat Farming |
| 112511 | Finfish Farming and Fish Hatcheries |
| 112512 | Shellfish Farming |
| 112519 | Other Aquaculture |
| 112910 | Apiculture |
| 112920 | Horses and Other Equine Production |
| 112930 | Fur-Bearing Animal and Rabbit Production |
| 112990 | All Other Animal Production |
| 113110 | Timber Tract Operations |
| 113210 | Forest Nurseries and Gathering of Forest Products |
| 113310 | Logging |
| 114111 | Finfish Fishing |
| 114112 | Shellfish Fishing |
| 114119 | Other Marine Fishing |
| 114210 | Hunting and Trapping |
| 115111 | Cotton Ginning |
| 115112 | Soil Preparation, Planting, and Cultivating |
| 115113 | Crop Harvesting, Primarily by Machine |
| 115114 | Postharvest Crop Activities (except Cotton Ginning) |
| 115115 | Farm Labor Contractors and Crew Leaders |
| 115116 | Farm Management Services |
| 115210 | Support Activities for Animal Production |
| 115310 | Support Activities for Forestry |
## 21 — Mining, Quarrying, and Oil and Gas Extraction
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------- |
| 211120 | Crude Petroleum Extraction |
| 211130 | Natural Gas Extraction |
| 212114 | Surface Coal Mining |
| 212115 | Underground Coal Mining |
| 212210 | Iron Ore Mining |
| 212220 | Gold Ore and Silver Ore Mining |
| 212230 | Copper, Nickel, Lead, and Zinc Mining |
| 212290 | Other Metal Ore Mining |
| 212311 | Dimension Stone Mining and Quarrying |
| 212312 | Crushed and Broken Limestone Mining and Quarrying |
| 212313 | Crushed and Broken Granite Mining and Quarrying |
| 212319 | Other Crushed and Broken Stone Mining and Quarrying |
| 212321 | Construction Sand and Gravel Mining |
| 212322 | Industrial Sand Mining |
| 212323 | Kaolin, Clay, and Ceramic and Refractory Minerals Mining |
| 212390 | Other Nonmetallic Mineral Mining and Quarrying |
| 213111 | Drilling Oil and Gas Wells |
| 213112 | Support Activities for Oil and Gas Operations |
| 213113 | Support Activities for Coal Mining |
| 213114 | Support Activities for Metal Mining |
| 213115 | Support Activities for Nonmetallic Minerals (except Fuels) Mining |
## 22 — Utilities
| NAICS Code | Industry Title |
| ---------- | -------------------------------------------- |
| 221111 | Hydroelectric Power Generation |
| 221112 | Fossil Fuel Electric Power Generation |
| 221113 | Nuclear Electric Power Generation |
| 221114 | Solar Electric Power Generation |
| 221115 | Wind Electric Power Generation |
| 221116 | Geothermal Electric Power Generation |
| 221117 | Biomass Electric Power Generation |
| 221118 | Other Electric Power Generation |
| 221121 | Electric Bulk Power Transmission and Control |
| 221122 | Electric Power Distribution |
| 221210 | Natural Gas Distribution |
| 221310 | Water Supply and Irrigation Systems |
| 221320 | Sewage Treatment Facilities |
| 221330 | Steam and Air-Conditioning Supply |
## 23 — Construction
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------- |
| 236115 | New Single-Family Housing Construction (except For-Sale Builders) |
| 236116 | New Multifamily Housing Construction (except For-Sale Builders) |
| 236117 | New Housing For-Sale Builders |
| 236118 | Residential Remodelers |
| 236210 | Industrial Building Construction |
| 236220 | Commercial and Institutional Building Construction |
| 237110 | Water and Sewer Line and Related Structures Construction |
| 237120 | Oil and Gas Pipeline and Related Structures Construction |
| 237130 | Power and Communication Line and Related Structures Construction |
| 237210 | Land Subdivision |
| 237310 | Highway, Street, and Bridge Construction |
| 237990 | Other Heavy and Civil Engineering Construction |
| 238110 | Poured Concrete Foundation and Structure Contractors |
| 238120 | Structural Steel and Precast Concrete Contractors |
| 238130 | Framing Contractors |
| 238140 | Masonry Contractors |
| 238150 | Glass and Glazing Contractors |
| 238160 | Roofing Contractors |
| 238170 | Siding Contractors |
| 238190 | Other Foundation, Structure, and Building Exterior Contractors |
| 238210 | Electrical Contractors and Other Wiring Installation Contractors |
| 238220 | Plumbing, Heating, and Air-Conditioning Contractors |
| 238290 | Other Building Equipment Contractors |
| 238310 | Drywall and Insulation Contractors |
| 238320 | Painting and Wall Covering Contractors |
| 238330 | Flooring Contractors |
| 238340 | Tile and Terrazzo Contractors |
| 238350 | Finish Carpentry Contractors |
| 238390 | Other Building Finishing Contractors |
| 238910 | Site Preparation Contractors |
| 238990 | All Other Specialty Trade Contractors |
## 31 — Manufacturing
| NAICS Code | Industry Title |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| 311111 | Dog and Cat Food Manufacturing |
| 311119 | Other Animal Food Manufacturing |
| 311211 | Flour Milling |
| 311212 | Rice Milling |
| 311213 | Malt Manufacturing |
| 311221 | Wet Corn Milling and Starch Manufacturing |
| 311224 | Soybean and Other Oilseed Processing |
| 311225 | Fats and Oils Refining and Blending |
| 311230 | Breakfast Cereal Manufacturing |
| 311313 | Beet Sugar Manufacturing |
| 311314 | Cane Sugar Manufacturing |
| 311340 | Nonchocolate Confectionery Manufacturing |
| 311351 | Chocolate and Confectionery Manufacturing from Cacao Beans |
| 311352 | Confectionery Manufacturing from Purchased Chocolate |
| 311411 | Frozen Fruit, Juice, and Vegetable Manufacturing |
| 311412 | Frozen Specialty Food Manufacturing |
| 311421 | Fruit and Vegetable Canning |
| 311422 | Specialty Canning |
| 311423 | Dried and Dehydrated Food Manufacturing |
| 311511 | Fluid Milk Manufacturing |
| 311512 | Creamery Butter Manufacturing |
| 311513 | Cheese Manufacturing |
| 311514 | Dry, Condensed, and Evaporated Dairy Product Manufacturing |
| 311520 | Ice Cream and Frozen Dessert Manufacturing |
| 311611 | Animal (except Poultry) Slaughtering |
| 311612 | Meat Processed from Carcasses |
| 311613 | Rendering and Meat Byproduct Processing |
| 311615 | Poultry Processing |
| 311710 | Seafood Product Preparation and Packaging |
| 311811 | Retail Bakeries |
| 311812 | Commercial Bakeries |
| 311813 | Frozen Cakes, Pies, and Other Pastries Manufacturing |
| 311821 | Cookie and Cracker Manufacturing |
| 311824 | Dry Pasta, Dough, and Flour Mixes Manufacturing from Purchased Flour |
| 311830 | Tortilla Manufacturing |
| 311911 | Roasted Nuts and Peanut Butter Manufacturing |
| 311919 | Other Snack Food Manufacturing |
| 311920 | Coffee and Tea Manufacturing |
| 311930 | Flavoring Syrup and Concentrate Manufacturing |
| 311941 | Mayonnaise, Dressing, and Other Prepared Sauce Manufacturing |
| 311942 | Spice and Extract Manufacturing |
| 311991 | Perishable Prepared Food Manufacturing |
| 311999 | All Other Miscellaneous Food Manufacturing |
| 312111 | Soft Drink Manufacturing |
| 312112 | Bottled Water Manufacturing |
| 312113 | Ice Manufacturing |
| 312120 | Breweries |
| 312130 | Wineries |
| 312140 | Distilleries |
| 312230 | Tobacco Manufacturing |
| 313110 | Fiber, Yarn, and Thread Mills |
| 313210 | Broadwoven Fabric Mills |
| 313220 | Narrow Fabric Mills and Schiffli Machine Embroidery |
| 313230 | Nonwoven Fabric Mills |
| 313240 | Knit Fabric Mills |
| 313310 | Textile and Fabric Finishing Mills |
| 313320 | Fabric Coating Mills |
| 314110 | Carpet and Rug Mills |
| 314120 | Curtain and Linen Mills |
| 314910 | Textile Bag and Canvas Mills |
| 314994 | Rope, Cordage, Twine, Tire Cord, and Tire Fabric Mills |
| 314999 | All Other Miscellaneous Textile Product Mills |
| 315120 | Apparel Knitting Mills |
| 315210 | Cut and Sew Apparel Contractors |
| 315250 | Cut and Sew Apparel Manufacturing (except Contractors) |
| 315990 | Apparel Accessories and Other Apparel Manufacturing |
| 316110 | Leather and Hide Tanning and Finishing |
| 316210 | Footwear Manufacturing |
| 316990 | Other Leather and Allied Product Manufacturing |
| 321113 | Sawmills |
| 321114 | Wood Preservation |
| 321211 | Hardwood Veneer and Plywood Manufacturing |
| 321212 | Softwood Veneer and Plywood Manufacturing |
| 321215 | Engineered Wood Member Manufacturing |
| 321219 | Reconstituted Wood Product Manufacturing |
| 321911 | Wood Window and Door Manufacturing |
| 321912 | Cut Stock, Resawing Lumber, and Planing |
| 321918 | Other Millwork (including Flooring) |
| 321920 | Wood Container and Pallet Manufacturing |
| 321991 | Manufactured Home (Mobile Home) Manufacturing |
| 321992 | Prefabricated Wood Building Manufacturing |
| 321999 | All Other Miscellaneous Wood Product Manufacturing |
| 322110 | Pulp Mills |
| 322120 | Paper Mills |
| 322130 | Paperboard Mills |
| 322211 | Corrugated and Solid Fiber Box Manufacturing |
| 322212 | Folding Paperboard Box Manufacturing |
| 322219 | Other Paperboard Container Manufacturing |
| 322220 | Paper Bag and Coated and Treated Paper Manufacturing |
| 322230 | Stationery Product Manufacturing |
| 322291 | Sanitary Paper Product Manufacturing |
| 322299 | All Other Converted Paper Product Manufacturing |
| 323111 | Commercial Printing (except Screen and Books) |
| 323113 | Commercial Screen Printing |
| 323117 | Books Printing |
| 323120 | Support Activities for Printing |
| 324110 | Petroleum Refineries |
| 324121 | Asphalt Paving Mixture and Block Manufacturing |
| 324122 | Asphalt Shingle and Coating Materials Manufacturing |
| 324191 | Petroleum Lubricating Oil and Grease Manufacturing |
| 324199 | All Other Petroleum and Coal Products Manufacturing |
| 325110 | Petrochemical Manufacturing |
| 325120 | Industrial Gas Manufacturing |
| 325130 | Synthetic Dye and Pigment Manufacturing |
| 325180 | Other Basic Inorganic Chemical Manufacturing |
| 325193 | Ethyl Alcohol Manufacturing |
| 325194 | Cyclic Crude, Intermediate, and Gum and Wood Chemical Manufacturing |
| 325199 | All Other Basic Organic Chemical Manufacturing |
| 325211 | Plastics Material and Resin Manufacturing |
| 325212 | Synthetic Rubber Manufacturing |
| 325220 | Artificial and Synthetic Fibers and Filaments Manufacturing |
| 325311 | Nitrogenous Fertilizer Manufacturing |
| 325312 | Phosphatic Fertilizer Manufacturing |
| 325314 | Fertilizer (Mixing Only) Manufacturing |
| 325315 | Compost Manufacturing |
| 325320 | Pesticide and Other Agricultural Chemical Manufacturing |
| 325411 | Medicinal and Botanical Manufacturing |
| 325412 | Pharmaceutical Preparation Manufacturing |
| 325413 | In-Vitro Diagnostic Substance Manufacturing |
| 325414 | Biological Product (except Diagnostic) Manufacturing |
| 325510 | Paint and Coating Manufacturing |
| 325520 | Adhesive Manufacturing |
| 325611 | Soap and Other Detergent Manufacturing |
| 325612 | Polish and Other Sanitation Good Manufacturing |
| 325613 | Surface Active Agent Manufacturing |
| 325620 | Toilet Preparation Manufacturing |
| 325910 | Printing Ink Manufacturing |
| 325920 | Explosives Manufacturing |
| 325991 | Custom Compounding of Purchased Resins |
| 325992 | Photographic Film, Paper, Plate, Chemical, and Copy Toner Manufacturing |
| 325998 | All Other Miscellaneous Chemical Product and Preparation Manufacturing |
| 326111 | Plastics Bag and Pouch Manufacturing |
| 326112 | Plastics Packaging Film and Sheet (including Laminated) Manufacturing |
| 326113 | Unlaminated Plastics Film and Sheet (except Packaging) Manufacturing |
| 326121 | Unlaminated Plastics Profile Shape Manufacturing |
| 326122 | Plastics Pipe and Pipe Fitting Manufacturing |
| 326130 | Laminated Plastics Plate, Sheet (except Packaging), and Shape Manufacturing |
| 326140 | Polystyrene Foam Product Manufacturing |
| 326150 | Urethane and Other Foam Product (except Polystyrene) Manufacturing |
| 326160 | Plastics Bottle Manufacturing |
| 326191 | Plastics Plumbing Fixture Manufacturing |
| 326199 | All Other Plastics Product Manufacturing |
| 326211 | Tire Manufacturing (except Retreading) |
| 326212 | Tire Retreading |
| 326220 | Rubber and Plastics Hoses and Belting Manufacturing |
| 326291 | Rubber Product Manufacturing for Mechanical Use |
| 326299 | All Other Rubber Product Manufacturing |
| 327110 | Pottery, Ceramics, and Plumbing Fixture Manufacturing |
| 327120 | Clay Building Material and Refractories Manufacturing |
| 327211 | Flat Glass Manufacturing |
| 327212 | Other Pressed and Blown Glass and Glassware Manufacturing |
| 327213 | Glass Container Manufacturing |
| 327215 | Glass Product Manufacturing Made of Purchased Glass |
| 327310 | Cement Manufacturing |
| 327320 | Ready-Mix Concrete Manufacturing |
| 327331 | Concrete Block and Brick Manufacturing |
| 327332 | Concrete Pipe Manufacturing |
| 327390 | Other Concrete Product Manufacturing |
| 327410 | Lime Manufacturing |
| 327420 | Gypsum Product Manufacturing |
| 327910 | Abrasive Product Manufacturing |
| 327991 | Cut Stone and Stone Product Manufacturing |
| 327992 | Ground or Treated Mineral and Earth Manufacturing |
| 327993 | Mineral Wool Manufacturing |
| 327999 | All Other Miscellaneous Nonmetallic Mineral Product Manufacturing |
| 331110 | Iron and Steel Mills and Ferroalloy Manufacturing |
| 331210 | Iron and Steel Pipe and Tube Manufacturing from Purchased Steel |
| 331221 | Rolled Steel Shape Manufacturing |
| 331222 | Steel Wire Drawing |
| 331313 | Alumina Refining and Primary Aluminum Production |
| 331314 | Secondary Smelting and Alloying of Aluminum |
| 331315 | Aluminum Sheet, Plate, and Foil Manufacturing |
| 331318 | Other Aluminum Rolling, Drawing, and Extruding |
| 331410 | Nonferrous Metal (except Aluminum) Smelting and Refining |
| 331420 | Copper Rolling, Drawing, Extruding, and Alloying |
| 331491 | Nonferrous Metal (except Copper and Aluminum) Rolling, Drawing, and Extruding |
| 331492 | Secondary Smelting, Refining, and Alloying of Nonferrous Metal (except Copper and Aluminum) |
| 331511 | Iron Foundries |
| 331512 | Steel Investment Foundries |
| 331513 | Steel Foundries (except Investment) |
| 331523 | Nonferrous Metal Die-Casting Foundries |
| 331524 | Aluminum Foundries (except Die-Casting) |
| 331529 | Other Nonferrous Metal Foundries (except Die-Casting) |
| 332111 | Iron and Steel Forging |
| 332112 | Nonferrous Forging |
| 332114 | Custom Roll Forming |
| 332117 | Powder Metallurgy Part Manufacturing |
| 332119 | Metal Crown, Closure, and Other Metal Stamping (except Automotive) |
| 332215 | Metal Kitchen Cookware, Utensil, Cutlery, and Flatware (except Precious) Manufacturing |
| 332216 | Saw Blade and Handtool Manufacturing |
| 332311 | Prefabricated Metal Building and Component Manufacturing |
| 332312 | Fabricated Structural Metal Manufacturing |
| 332313 | Plate Work Manufacturing |
| 332321 | Metal Window and Door Manufacturing |
| 332322 | Sheet Metal Work Manufacturing |
| 332323 | Ornamental and Architectural Metal Work Manufacturing |
| 332410 | Power Boiler and Heat Exchanger Manufacturing |
| 332420 | Metal Tank (Heavy Gauge) Manufacturing |
| 332431 | Metal Can Manufacturing |
| 332439 | Other Metal Container Manufacturing |
| 332510 | Hardware Manufacturing |
| 332613 | Spring Manufacturing |
| 332618 | Other Fabricated Wire Product Manufacturing |
| 332710 | Machine Shops |
| 332721 | Precision Turned Product Manufacturing |
| 332722 | Bolt, Nut, Screw, Rivet, and Washer Manufacturing |
| 332811 | Metal Heat Treating |
| 332812 | Metal Coating, Engraving (except Jewelry and Silverware), and Allied Services to Manufacturers |
| 332813 | Electroplating, Plating, Polishing, Anodizing, and Coloring |
| 332911 | Industrial Valve Manufacturing |
| 332912 | Fluid Power Valve and Hose Fitting Manufacturing |
| 332913 | Plumbing Fixture Fitting and Trim Manufacturing |
| 332919 | Other Metal Valve and Pipe Fitting Manufacturing |
| 332991 | Ball and Roller Bearing Manufacturing |
| 332992 | Small Arms Ammunition Manufacturing |
| 332993 | Ammunition (except Small Arms) Manufacturing |
| 332994 | Small Arms, Ordnance, and Ordnance Accessories Manufacturing |
| 332996 | Fabricated Pipe and Pipe Fitting Manufacturing |
| 332999 | All Other Miscellaneous Fabricated Metal Product Manufacturing |
| 333111 | Farm Machinery and Equipment Manufacturing |
| 333112 | Lawn and Garden Tractor and Home Lawn and Garden Equipment Manufacturing |
| 333120 | Construction Machinery Manufacturing |
| 333131 | Mining Machinery and Equipment Manufacturing |
| 333132 | Oil and Gas Field Machinery and Equipment Manufacturing |
| 333241 | Food Product Machinery Manufacturing |
| 333242 | Semiconductor Machinery Manufacturing |
| 333243 | Sawmill, Woodworking, and Paper Machinery Manufacturing |
| 333248 | All Other Industrial Machinery Manufacturing |
| 333310 | Commercial and Service Industry Machinery Manufacturing |
| 333413 | Industrial and Commercial Fan and Blower and Air Purification Equipment Manufacturing |
| 333414 | Heating Equipment (except Warm Air Furnaces) Manufacturing |
| 333415 | Air-Conditioning and Warm Air Heating Equipment and Commercial and Industrial Refrigeration Equipment Manufacturing |
| 333511 | Industrial Mold Manufacturing |
| 333514 | Special Die and Tool, Die Set, Jig, and Fixture Manufacturing |
| 333515 | Cutting Tool and Machine Tool Accessory Manufacturing |
| 333517 | Machine Tool Manufacturing |
| 333519 | Rolling Mill and Other Metalworking Machinery Manufacturing |
| 333611 | Turbine and Turbine Generator Set Units Manufacturing |
| 333612 | Speed Changer, Industrial High-Speed Drive, and Gear Manufacturing |
| 333613 | Mechanical Power Transmission Equipment Manufacturing |
| 333618 | Other Engine Equipment Manufacturing |
| 333912 | Air and Gas Compressor Manufacturing |
| 333914 | Measuring, Dispensing, and Other Pumping Equipment Manufacturing |
| 333921 | Elevator and Moving Stairway Manufacturing |
| 333922 | Conveyor and Conveying Equipment Manufacturing |
| 333923 | Overhead Traveling Crane, Hoist, and Monorail System Manufacturing |
| 333924 | Industrial Truck, Tractor, Trailer, and Stacker Machinery Manufacturing |
| 333991 | Power-Driven Handtool Manufacturing |
| 333992 | Welding and Soldering Equipment Manufacturing |
| 333993 | Packaging Machinery Manufacturing |
| 333994 | Industrial Process Furnace and Oven Manufacturing |
| 333995 | Fluid Power Cylinder and Actuator Manufacturing |
| 333996 | Fluid Power Pump and Motor Manufacturing |
| 333998 | All Other Miscellaneous General Purpose Machinery Manufacturing |
| 334111 | Electronic Computer Manufacturing |
| 334112 | Computer Storage Device Manufacturing |
| 334118 | Computer Terminal and Other Computer Peripheral Equipment Manufacturing |
| 334210 | Telephone Apparatus Manufacturing |
| 334220 | Radio and Television Broadcasting and Wireless Communications Equipment Manufacturing |
| 334290 | Other Communications Equipment Manufacturing |
| 334310 | Audio and Video Equipment Manufacturing |
| 334412 | Bare Printed Circuit Board Manufacturing |
| 334413 | Semiconductor and Related Device Manufacturing |
| 334416 | Capacitor, Resistor, Coil, Transformer, and Other Inductor Manufacturing |
| 334417 | Electronic Connector Manufacturing |
| 334418 | Printed Circuit Assembly (Electronic Assembly) Manufacturing |
| 334419 | Other Electronic Component Manufacturing |
| 334510 | Electromedical and Electrotherapeutic Apparatus Manufacturing |
| 334511 | Search, Detection, Navigation, Guidance, Aeronautical, and Nautical System and Instrument Manufacturing |
| 334512 | Automatic Environmental Control Manufacturing for Residential, Commercial, and Appliance Use |
| 334513 | Instruments and Related Products Manufacturing for Measuring, Displaying, and Controlling Industrial Process Variables |
| 334514 | Totalizing Fluid Meter and Counting Device Manufacturing |
| 334515 | Instrument Manufacturing for Measuring and Testing Electricity and Electrical Signals |
| 334516 | Analytical Laboratory Instrument Manufacturing |
| 334517 | Irradiation Apparatus Manufacturing |
| 334519 | Other Measuring and Controlling Device Manufacturing |
| 334610 | Manufacturing and Reproducing Magnetic and Optical Media |
| 335131 | Residential Electric Lighting Fixture Manufacturing |
| 335132 | Commercial, Industrial, and Institutional Electric Lighting Fixture Manufacturing |
| 335139 | Electric Lamp Bulb and Other Lighting Equipment Manufacturing |
| 335210 | Small Electrical Appliance Manufacturing |
| 335220 | Major Household Appliance Manufacturing |
| 335311 | Power, Distribution, and Specialty Transformer Manufacturing |
| 335312 | Motor and Generator Manufacturing |
| 335313 | Switchgear and Switchboard Apparatus Manufacturing |
| 335314 | Relay and Industrial Control Manufacturing |
| 335910 | Battery Manufacturing |
| 335921 | Fiber Optic Cable Manufacturing |
| 335929 | Other Communication and Energy Wire Manufacturing |
| 335931 | Current-Carrying Wiring Device Manufacturing |
| 335932 | Noncurrent-Carrying Wiring Device Manufacturing |
| 335991 | Carbon and Graphite Product Manufacturing |
| 335999 | All Other Miscellaneous Electrical Equipment and Component Manufacturing |
| 336110 | Automobile and Light Duty Motor Vehicle Manufacturing |
| 336120 | Heavy Duty Truck Manufacturing |
| 336211 | Motor Vehicle Body Manufacturing |
| 336212 | Truck Trailer Manufacturing |
| 336213 | Motor Home Manufacturing |
| 336214 | Travel Trailer and Camper Manufacturing |
| 336310 | Motor Vehicle Gasoline Engine and Engine Parts Manufacturing |
| 336320 | Motor Vehicle Electrical and Electronic Equipment Manufacturing |
| 336330 | Motor Vehicle Steering and Suspension Components (except Spring) Manufacturing |
| 336340 | Motor Vehicle Brake System Manufacturing |
| 336350 | Motor Vehicle Transmission and Power Train Parts Manufacturing |
| 336360 | Motor Vehicle Seating and Interior Trim Manufacturing |
| 336370 | Motor Vehicle Metal Stamping |
| 336390 | Other Motor Vehicle Parts Manufacturing |
| 336411 | Aircraft Manufacturing |
| 336412 | Aircraft Engine and Engine Parts Manufacturing |
| 336413 | Other Aircraft Parts and Auxiliary Equipment Manufacturing |
| 336414 | Guided Missile and Space Vehicle Manufacturing |
| 336415 | Guided Missile and Space Vehicle Propulsion Unit and Propulsion Unit Parts Manufacturing |
| 336419 | Other Guided Missile and Space Vehicle Parts and Auxiliary Equipment Manufacturing |
| 336510 | Railroad Rolling Stock Manufacturing |
| 336611 | Ship Building and Repairing |
| 336612 | Boat Building |
| 336991 | Motorcycle, Bicycle, and Parts Manufacturing |
| 336992 | Military Armored Vehicle, Tank, and Tank Component Manufacturing |
| 336999 | All Other Transportation Equipment Manufacturing |
| 337110 | Wood Kitchen Cabinet and Countertop Manufacturing |
| 337121 | Upholstered Household Furniture Manufacturing |
| 337122 | Nonupholstered Wood Household Furniture Manufacturing |
| 337126 | Household Furniture (except Wood and Upholstered) Manufacturing |
| 337127 | Institutional Furniture Manufacturing |
| 337211 | Wood Office Furniture Manufacturing |
| 337212 | Custom Architectural Woodwork and Millwork Manufacturing |
| 337214 | Office Furniture (except Wood) Manufacturing |
| 337215 | Showcase, Partition, Shelving, and Locker Manufacturing |
| 337910 | Mattress Manufacturing |
| 337920 | Blind and Shade Manufacturing |
| 339112 | Surgical and Medical Instrument Manufacturing |
| 339113 | Surgical Appliance and Supplies Manufacturing |
| 339114 | Dental Equipment and Supplies Manufacturing |
| 339115 | Ophthalmic Goods Manufacturing |
| 339116 | Dental Laboratories |
| 339910 | Jewelry and Silverware Manufacturing |
| 339920 | Sporting and Athletic Goods Manufacturing |
| 339930 | Doll, Toy, and Game Manufacturing |
| 339940 | Office Supplies (except Paper) Manufacturing |
| 339950 | Sign Manufacturing |
| 339991 | Gasket, Packing, and Sealing Device Manufacturing |
| 339992 | Musical Instrument Manufacturing |
| 339993 | Fastener, Button, Needle, and Pin Manufacturing |
| 339994 | Broom, Brush, and Mop Manufacturing |
| 339995 | Burial Casket Manufacturing |
| 339999 | All Other Miscellaneous Manufacturing |
## 42 — Wholesale Trade
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------------------------------- |
| 423110 | Automobile and Other Motor Vehicle Merchant Wholesalers |
| 423120 | Motor Vehicle Supplies and New Parts Merchant Wholesalers |
| 423130 | Tire and Tube Merchant Wholesalers |
| 423140 | Motor Vehicle Parts (Used) Merchant Wholesalers |
| 423210 | Furniture Merchant Wholesalers |
| 423220 | Home Furnishing Merchant Wholesalers |
| 423310 | Lumber, Plywood, Millwork, and Wood Panel Merchant Wholesalers |
| 423320 | Brick, Stone, and Related Construction Material Merchant Wholesalers |
| 423330 | Roofing, Siding, and Insulation Material Merchant Wholesalers |
| 423390 | Other Construction Material Merchant Wholesalers |
| 423410 | Photographic Equipment and Supplies Merchant Wholesalers |
| 423420 | Office Equipment Merchant Wholesalers |
| 423430 | Computer and Computer Peripheral Equipment and Software Merchant Wholesalers |
| 423440 | Other Commercial Equipment Merchant Wholesalers |
| 423450 | Medical, Dental, and Hospital Equipment and Supplies Merchant Wholesalers |
| 423460 | Ophthalmic Goods Merchant Wholesalers |
| 423490 | Other Professional Equipment and Supplies Merchant Wholesalers |
| 423510 | Metal Service Centers and Other Metal Merchant Wholesalers |
| 423520 | Coal and Other Mineral and Ore Merchant Wholesalers |
| 423610 | Electrical Apparatus and Equipment, Wiring Supplies, and Related Equipment Merchant Wholesalers |
| 423620 | Household Appliances, Electric Housewares, and Consumer Electronics Merchant Wholesalers |
| 423690 | Other Electronic Parts and Equipment Merchant Wholesalers |
| 423710 | Hardware Merchant Wholesalers |
| 423720 | Plumbing and Heating Equipment and Supplies (Hydronics) Merchant Wholesalers |
| 423730 | Warm Air Heating and Air-Conditioning Equipment and Supplies Merchant Wholesalers |
| 423740 | Refrigeration Equipment and Supplies Merchant Wholesalers |
| 423810 | Construction and Mining (except Oil Well) Machinery and Equipment Merchant Wholesalers |
| 423820 | Farm and Garden Machinery and Equipment Merchant Wholesalers |
| 423830 | Industrial Machinery and Equipment Merchant Wholesalers |
| 423840 | Industrial Supplies Merchant Wholesalers |
| 423850 | Service Establishment Equipment and Supplies Merchant Wholesalers |
| 423860 | Transportation Equipment and Supplies (except Motor Vehicle) Merchant Wholesalers |
| 423910 | Sporting and Recreational Goods and Supplies Merchant Wholesalers |
| 423920 | Toy and Hobby Goods and Supplies Merchant Wholesalers |
| 423930 | Recyclable Material Merchant Wholesalers |
| 423940 | Jewelry, Watch, Precious Stone, and Precious Metal Merchant Wholesalers |
| 423990 | Other Miscellaneous Durable Goods Merchant Wholesalers |
| 424110 | Printing and Writing Paper Merchant Wholesalers |
| 424120 | Stationery and Office Supplies Merchant Wholesalers |
| 424130 | Industrial and Personal Service Paper Merchant Wholesalers |
| 424210 | Drugs and Druggists' Sundries Merchant Wholesalers |
| 424310 | Piece Goods, Notions, and Other Dry Goods Merchant Wholesalers |
| 424340 | Footwear Merchant Wholesalers |
| 424350 | Clothing and Clothing Accessories Merchant Wholesalers |
| 424410 | General Line Grocery Merchant Wholesalers |
| 424420 | Packaged Frozen Food Merchant Wholesalers |
| 424430 | Dairy Product (except Dried or Canned) Merchant Wholesalers |
| 424440 | Poultry and Poultry Product Merchant Wholesalers |
| 424450 | Confectionery Merchant Wholesalers |
| 424460 | Fish and Seafood Merchant Wholesalers |
| 424470 | Meat and Meat Product Merchant Wholesalers |
| 424480 | Fresh Fruit and Vegetable Merchant Wholesalers |
| 424490 | Other Grocery and Related Products Merchant Wholesalers |
| 424510 | Grain and Field Bean Merchant Wholesalers |
| 424520 | Livestock Merchant Wholesalers |
| 424590 | Other Farm Product Raw Material Merchant Wholesalers |
| 424610 | Plastics Materials and Basic Forms and Shapes Merchant Wholesalers |
| 424690 | Other Chemical and Allied Products Merchant Wholesalers |
| 424710 | Petroleum Bulk Stations and Terminals |
| 424720 | Petroleum and Petroleum Products Merchant Wholesalers (except Bulk Stations and Terminals) |
| 424810 | Beer and Ale Merchant Wholesalers |
| 424820 | Wine and Distilled Alcoholic Beverage Merchant Wholesalers |
| 424910 | Farm Supplies Merchant Wholesalers |
| 424920 | Book, Periodical, and Newspaper Merchant Wholesalers |
| 424930 | Flower, Nursery Stock, and Florists' Supplies Merchant Wholesalers |
| 424940 | Tobacco Product and Electronic Cigarette Merchant Wholesalers |
| 424950 | Paint, Varnish, and Supplies Merchant Wholesalers |
| 424990 | Other Miscellaneous Nondurable Goods Merchant Wholesalers |
| 425120 | Wholesale Trade Agents and Brokers |
## 44 — Retail Trade
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------- |
| 441110 | New Car Dealers |
| 441120 | Used Car Dealers |
| 441210 | Recreational Vehicle Dealers |
| 441222 | Boat Dealers |
| 441227 | Motorcycle, ATV, and All Other Motor Vehicle Dealers |
| 441330 | Automotive Parts and Accessories Retailers |
| 441340 | Tire Dealers |
| 444110 | Home Centers |
| 444120 | Paint and Wallpaper Retailers |
| 444140 | Hardware Retailers |
| 444180 | Other Building Material Dealers |
| 444230 | Outdoor Power Equipment Retailers |
| 444240 | Nursery, Garden Center, and Farm Supply Retailers |
| 445110 | Supermarkets and Other Grocery Retailers (except Convenience Retailers) |
| 445131 | Convenience Retailers |
| 445132 | Vending Machine Operators |
| 445230 | Fruit and Vegetable Retailers |
| 445240 | Meat Retailers |
| 445250 | Fish and Seafood Retailers |
| 445291 | Baked Goods Retailers |
| 445292 | Confectionery and Nut Retailers |
| 445298 | All Other Specialty Food Retailers |
| 445320 | Beer, Wine, and Liquor Retailers |
| 449110 | Furniture Retailers |
| 449121 | Floor Covering Retailers |
| 449122 | Window Treatment Retailers |
| 449129 | All Other Home Furnishings Retailers |
| 449210 | Electronics and Appliance Retailers |
| 455110 | Department Stores |
| 455211 | Warehouse Clubs and Supercenters |
| 455219 | All Other General Merchandise Retailers |
| 456110 | Pharmacies and Drug Retailers |
| 456120 | Cosmetics, Beauty Supplies, and Perfume Retailers |
| 456130 | Optical Goods Retailers |
| 456191 | Food (Health) Supplement Retailers |
| 456199 | All Other Health and Personal Care Retailers |
| 457110 | Gasoline Stations with Convenience Stores |
| 457120 | Other Gasoline Stations |
| 457210 | Fuel Dealers |
| 458110 | Clothing and Clothing Accessories Retailers |
| 458210 | Shoe Retailers |
| 458310 | Jewelry Retailers |
| 458320 | Luggage and Leather Goods Retailers |
| 459110 | Sporting Goods Retailers |
| 459120 | Hobby, Toy, and Game Retailers |
| 459130 | Sewing, Needlework, and Piece Goods Retailers |
| 459140 | Musical Instrument and Supplies Retailers |
| 459210 | Book Retailers and News Dealers |
| 459310 | Florists |
| 459410 | Office Supplies and Stationery Retailers |
| 459420 | Gift, Novelty, and Souvenir Retailers |
| 459510 | Used Merchandise Retailers |
| 459910 | Pet and Pet Supplies Retailers |
| 459920 | Art Dealers |
| 459930 | Manufactured (Mobile) Home Dealers |
| 459991 | Tobacco, Electronic Cigarette, and Other Smoking Supplies Retailers |
| 459999 | All Other Miscellaneous Retailers |
## 48 — Transportation and Warehousing
| NAICS Code | Industry Title |
| ---------- | --------------------------------------------------------------- |
| 481111 | Scheduled Passenger Air Transportation |
| 481112 | Scheduled Freight Air Transportation |
| 481211 | Nonscheduled Chartered Passenger Air Transportation |
| 481212 | Nonscheduled Chartered Freight Air Transportation |
| 481219 | Other Nonscheduled Air Transportation |
| 482111 | Line-Haul Railroads |
| 482112 | Short Line Railroads |
| 483111 | Deep Sea Freight Transportation |
| 483112 | Deep Sea Passenger Transportation |
| 483113 | Coastal and Great Lakes Freight Transportation |
| 483114 | Coastal and Great Lakes Passenger Transportation |
| 483211 | Inland Water Freight Transportation |
| 483212 | Inland Water Passenger Transportation |
| 484110 | General Freight Trucking, Local |
| 484121 | General Freight Trucking, Long-Distance, Truckload |
| 484122 | General Freight Trucking, Long-Distance, Less Than Truckload |
| 484210 | Used Household and Office Goods Moving |
| 484220 | Specialized Freight (except Used Goods) Trucking, Local |
| 484230 | Specialized Freight (except Used Goods) Trucking, Long-Distance |
| 485111 | Mixed Mode Transit Systems |
| 485112 | Commuter Rail Systems |
| 485113 | Bus and Other Motor Vehicle Transit Systems |
| 485119 | Other Urban Transit Systems |
| 485210 | Interurban and Rural Bus Transportation |
| 485310 | Taxi and Ridesharing Services |
| 485320 | Limousine Service |
| 485410 | School and Employee Bus Transportation |
| 485510 | Charter Bus Industry |
| 485991 | Special Needs Transportation |
| 485999 | All Other Transit and Ground Passenger Transportation |
| 486110 | Pipeline Transportation of Crude Oil |
| 486210 | Pipeline Transportation of Natural Gas |
| 486910 | Pipeline Transportation of Refined Petroleum Products |
| 486990 | All Other Pipeline Transportation |
| 487110 | Scenic and Sightseeing Transportation, Land |
| 487210 | Scenic and Sightseeing Transportation, Water |
| 487990 | Scenic and Sightseeing Transportation, Other |
| 488111 | Air Traffic Control |
| 488119 | Other Airport Operations |
| 488190 | Other Support Activities for Air Transportation |
| 488210 | Support Activities for Rail Transportation |
| 488310 | Port and Harbor Operations |
| 488320 | Marine Cargo Handling |
| 488330 | Navigational Services to Shipping |
| 488390 | Other Support Activities for Water Transportation |
| 488410 | Motor Vehicle Towing |
| 488490 | Other Support Activities for Road Transportation |
| 488510 | Freight Transportation Arrangement |
| 488991 | Packing and Crating |
| 488999 | All Other Support Activities for Transportation |
| 491110 | Postal Service |
| 492110 | Couriers and Express Delivery Services |
| 492210 | Local Messengers and Local Delivery |
| 493110 | General Warehousing and Storage |
| 493120 | Refrigerated Warehousing and Storage |
| 493130 | Farm Product Warehousing and Storage |
| 493190 | Other Warehousing and Storage |
## 51 — Information
| NAICS Code | Industry Title |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| 512110 | Motion Picture and Video Production |
| 512120 | Motion Picture and Video Distribution |
| 512131 | Motion Picture Theaters (except Drive-Ins) |
| 512132 | Drive-In Motion Picture Theaters |
| 512191 | Teleproduction and Other Postproduction Services |
| 512199 | Other Motion Picture and Video Industries |
| 512230 | Music Publishers |
| 512240 | Sound Recording Studios |
| 512250 | Record Production and Distribution |
| 512290 | Other Sound Recording Industries |
| 513110 | Newspaper Publishers |
| 513120 | Periodical Publishers |
| 513130 | Book Publishers |
| 513140 | Directory and Mailing List Publishers |
| 513191 | Greeting Card Publishers |
| 513199 | All Other Publishers |
| 513210 | Software Publishers |
| 516110 | Radio Broadcasting Stations |
| 516120 | Television Broadcasting Stations |
| 516210 | Media Streaming Distribution Services, Social Networks, and Other Media Networks and Content Providers |
| 517111 | Wired Telecommunications Carriers |
| 517112 | Wireless Telecommunications Carriers (except Satellite) |
| 517121 | Telecommunications Resellers |
| 517122 | Agents for Wireless Telecommunications Services |
| 517410 | Satellite Telecommunications |
| 517810 | All Other Telecommunications |
| 518210 | Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services |
| 519210 | Libraries and Archives |
| 519290 | Web Search Portals and All Other Information Services |
## 52 — Finance and Insurance
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------------------------------- |
| 521110 | Monetary Authorities-Central Bank |
| 522110 | Commercial Banking |
| 522130 | Credit Unions |
| 522180 | Savings Institutions and Other Depository Credit Intermediation |
| 522210 | Credit Card Issuing |
| 522220 | Sales Financing |
| 522291 | Consumer Lending |
| 522292 | Real Estate Credit |
| 522299 | International, Secondary Market, and All Other Nondepository Credit Intermediation |
| 522310 | Mortgage and Nonmortgage Loan Brokers |
| 522320 | Financial Transactions Processing, Reserve, and Clearinghouse Activities |
| 522390 | Other Activities Related to Credit Intermediation |
| 523150 | Investment Banking and Securities Intermediation |
| 523160 | Commodity Contracts Intermediation |
| 523210 | Securities and Commodity Exchanges |
| 523910 | Miscellaneous Intermediation |
| 523940 | Portfolio Management and Investment Advice |
| 523991 | Trust, Fiduciary, and Custody Activities |
| 523999 | Miscellaneous Financial Investment Activities |
| 524113 | Direct Life Insurance Carriers |
| 524114 | Direct Health and Medical Insurance Carriers |
| 524126 | Direct Property and Casualty Insurance Carriers |
| 524127 | Direct Title Insurance Carriers |
| 524128 | Other Direct Insurance (except Life, Health, and Medical) Carriers |
| 524130 | Reinsurance Carriers |
| 524210 | Insurance Agencies and Brokerages |
| 524291 | Claims Adjusting |
| 524292 | Pharmacy Benefit Management and Other Third Party Administration of Insurance and Pension Funds |
| 524298 | All Other Insurance Related Activities |
| 525110 | Pension Funds |
| 525120 | Health and Welfare Funds |
| 525190 | Other Insurance Funds |
| 525910 | Open-End Investment Funds |
| 525920 | Trusts, Estates, and Agency Accounts |
| 525990 | Other Financial Vehicles |
## 53 — Real Estate and Rental and Leasing
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------------- |
| 531110 | Lessors of Residential Buildings and Dwellings |
| 531120 | Lessors of Nonresidential Buildings (except Miniwarehouses) |
| 531130 | Lessors of Miniwarehouses and Self-Storage Units |
| 531190 | Lessors of Other Real Estate Property |
| 531210 | Offices of Real Estate Agents and Brokers |
| 531311 | Residential Property Managers |
| 531312 | Nonresidential Property Managers |
| 531320 | Offices of Real Estate Appraisers |
| 531390 | Other Activities Related to Real Estate |
| 532111 | Passenger Car Rental |
| 532112 | Passenger Car Leasing |
| 532120 | Truck, Utility Trailer, and RV (Recreational Vehicle) Rental and Leasing |
| 532210 | Consumer Electronics and Appliances Rental |
| 532281 | Formal Wear and Costume Rental |
| 532282 | Video Tape and Disc Rental |
| 532283 | Home Health Equipment Rental |
| 532284 | Recreational Goods Rental |
| 532289 | All Other Consumer Goods Rental |
| 532310 | General Rental Centers |
| 532411 | Commercial Air, Rail, and Water Transportation Equipment Rental and Leasing |
| 532412 | Construction, Mining, and Forestry Machinery and Equipment Rental and Leasing |
| 532420 | Office Machinery and Equipment Rental and Leasing |
| 532490 | Other Commercial and Industrial Machinery and Equipment Rental and Leasing |
| 533110 | Lessors of Nonfinancial Intangible Assets (except Copyrighted Works) |
## 54 — Professional, Scientific, and Technical Services
| NAICS Code | Industry Title |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| 541110 | Offices of Lawyers |
| 541120 | Offices of Notaries |
| 541191 | Title Abstract and Settlement Offices |
| 541199 | All Other Legal Services |
| 541211 | Offices of Certified Public Accountants |
| 541213 | Tax Preparation Services |
| 541214 | Payroll Services |
| 541219 | Other Accounting Services |
| 541310 | Architectural Services |
| 541320 | Landscape Architectural Services |
| 541330 | Engineering Services |
| 541340 | Drafting Services |
| 541350 | Building Inspection Services |
| 541360 | Geophysical Surveying and Mapping Services |
| 541370 | Surveying and Mapping (except Geophysical) Services |
| 541380 | Testing Laboratories and Services |
| 541410 | Interior Design Services |
| 541420 | Industrial Design Services |
| 541430 | Graphic Design Services |
| 541490 | Other Specialized Design Services |
| 541511 | Custom Computer Programming Services |
| 541512 | Computer Systems Design Services |
| 541513 | Computer Facilities Management Services |
| 541519 | Other Computer Related Services |
| 541611 | Administrative Management and General Management Consulting Services |
| 541612 | Human Resources Consulting Services |
| 541613 | Marketing Consulting Services |
| 541614 | Process, Physical Distribution, and Logistics Consulting Services |
| 541618 | Other Management Consulting Services |
| 541620 | Environmental Consulting Services |
| 541690 | Other Scientific and Technical Consulting Services |
| 541713 | Research and Development in Nanotechnology |
| 541714 | Research and Development in Biotechnology (except Nanobiotechnology) |
| 541715 | Research and Development in the Physical, Engineering, and Life Sciences (except Nanotechnology and Biotechnology) |
| 541720 | Research and Development in the Social Sciences and Humanities |
| 541810 | Advertising Agencies |
| 541820 | Public Relations Agencies |
| 541830 | Media Buying Agencies |
| 541840 | Media Representatives |
| 541850 | Indoor and Outdoor Display Advertising |
| 541860 | Direct Mail Advertising |
| 541870 | Advertising Material Distribution Services |
| 541890 | Other Services Related to Advertising |
| 541910 | Marketing Research and Public Opinion Polling |
| 541921 | Photography Studios, Portrait |
| 541922 | Commercial Photography |
| 541930 | Translation and Interpretation Services |
| 541940 | Veterinary Services |
| 541990 | All Other Professional, Scientific, and Technical Services |
## 55 — Management of Companies and Enterprises
| NAICS Code | Industry Title |
| ---------- | ---------------------------------------------------- |
| 551111 | Offices of Bank Holding Companies |
| 551112 | Offices of Other Holding Companies |
| 551114 | Corporate, Subsidiary, and Regional Managing Offices |
## 56 — Administrative and Support and Waste Management and Remediation Services
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------- |
| 561110 | Office Administrative Services |
| 561210 | Facilities Support Services |
| 561311 | Employment Placement Agencies |
| 561312 | Executive Search Services |
| 561320 | Temporary Help Services |
| 561330 | Professional Employer Organizations |
| 561410 | Document Preparation Services |
| 561421 | Telephone Answering Services |
| 561422 | Telemarketing Bureaus and Other Contact Centers |
| 561431 | Private Mail Centers |
| 561439 | Other Business Service Centers (including Copy Shops) |
| 561440 | Collection Agencies |
| 561450 | Credit Bureaus |
| 561491 | Repossession Services |
| 561492 | Court Reporting and Stenotype Services |
| 561499 | All Other Business Support Services |
| 561510 | Travel Agencies |
| 561520 | Tour Operators |
| 561591 | Convention and Visitors Bureaus |
| 561599 | All Other Travel Arrangement and Reservation Services |
| 561611 | Investigation and Personal Background Check Services |
| 561612 | Security Guards and Patrol Services |
| 561613 | Armored Car Services |
| 561621 | Security Systems Services (except Locksmiths) |
| 561622 | Locksmiths |
| 561710 | Exterminating and Pest Control Services |
| 561720 | Janitorial Services |
| 561730 | Landscaping Services |
| 561740 | Carpet and Upholstery Cleaning Services |
| 561790 | Other Services to Buildings and Dwellings |
| 561910 | Packaging and Labeling Services |
| 561920 | Convention and Trade Show Organizers |
| 561990 | All Other Support Services |
| 562111 | Solid Waste Collection |
| 562112 | Hazardous Waste Collection |
| 562119 | Other Waste Collection |
| 562211 | Hazardous Waste Treatment and Disposal |
| 562212 | Solid Waste Landfill |
| 562213 | Solid Waste Combustors and Incinerators |
| 562219 | Other Nonhazardous Waste Treatment and Disposal |
| 562910 | Remediation Services |
| 562920 | Materials Recovery Facilities |
| 562991 | Septic Tank and Related Services |
| 562998 | All Other Miscellaneous Waste Management Services |
## 61 — Educational Services
| NAICS Code | Industry Title |
| ---------- | ------------------------------------------------ |
| 611110 | Elementary and Secondary Schools |
| 611210 | Junior Colleges |
| 611310 | Colleges, Universities, and Professional Schools |
| 611410 | Business and Secretarial Schools |
| 611420 | Computer Training |
| 611430 | Professional and Management Development Training |
| 611511 | Cosmetology and Barber Schools |
| 611512 | Flight Training |
| 611513 | Apprenticeship Training |
| 611519 | Other Technical and Trade Schools |
| 611610 | Fine Arts Schools |
| 611620 | Sports and Recreation Instruction |
| 611630 | Language Schools |
| 611691 | Exam Preparation and Tutoring |
| 611692 | Automobile Driving Schools |
| 611699 | All Other Miscellaneous Schools and Instruction |
| 611710 | Educational Support Services |
## 62 — Health Care and Social Assistance
| NAICS Code | Industry Title |
| ---------- | ------------------------------------------------------------------------- |
| 621111 | Offices of Physicians (except Mental Health Specialists) |
| 621112 | Offices of Physicians, Mental Health Specialists |
| 621210 | Offices of Dentists |
| 621310 | Offices of Chiropractors |
| 621320 | Offices of Optometrists |
| 621330 | Offices of Mental Health Practitioners (except Physicians) |
| 621340 | Offices of Physical, Occupational and Speech Therapists, and Audiologists |
| 621391 | Offices of Podiatrists |
| 621399 | Offices of All Other Miscellaneous Health Practitioners |
| 621410 | Family Planning Centers |
| 621420 | Outpatient Mental Health and Substance Abuse Centers |
| 621491 | HMO Medical Centers |
| 621492 | Kidney Dialysis Centers |
| 621493 | Freestanding Ambulatory Surgical and Emergency Centers |
| 621498 | All Other Outpatient Care Centers |
| 621511 | Medical Laboratories |
| 621512 | Diagnostic Imaging Centers |
| 621610 | Home Health Care Services |
| 621910 | Ambulance Services |
| 621991 | Blood and Organ Banks |
| 621999 | All Other Miscellaneous Ambulatory Health Care Services |
| 622110 | General Medical and Surgical Hospitals |
| 622210 | Psychiatric and Substance Abuse Hospitals |
| 622310 | Specialty (except Psychiatric and Substance Abuse) Hospitals |
| 623110 | Nursing Care Facilities (Skilled Nursing Facilities) |
| 623210 | Residential Intellectual and Developmental Disability Facilities |
| 623220 | Residential Mental Health and Substance Abuse Facilities |
| 623311 | Continuing Care Retirement Communities |
| 623312 | Assisted Living Facilities for the Elderly |
| 623990 | Other Residential Care Facilities |
| 624110 | Child and Youth Services |
| 624120 | Services for the Elderly and Persons with Disabilities |
| 624190 | Other Individual and Family Services |
| 624210 | Community Food Services |
| 624221 | Temporary Shelters |
| 624229 | Other Community Housing Services |
| 624230 | Emergency and Other Relief Services |
| 624310 | Vocational Rehabilitation Services |
| 624410 | Child Care Services |
## 71 — Arts, Entertainment, and Recreation
| NAICS Code | Industry Title |
| ---------- | --------------------------------------------------------------------------------- |
| 711110 | Theater Companies and Dinner Theaters |
| 711120 | Dance Companies |
| 711130 | Musical Groups and Artists |
| 711190 | Other Performing Arts Companies |
| 711211 | Sports Teams and Clubs |
| 711212 | Racetracks |
| 711219 | Other Spectator Sports |
| 711310 | Promoters of Performing Arts, Sports, and Similar Events with Facilities |
| 711320 | Promoters of Performing Arts, Sports, and Similar Events without Facilities |
| 711410 | Agents and Managers for Artists, Athletes, Entertainers, and Other Public Figures |
| 711510 | Independent Artists, Writers, and Performers |
| 712110 | Museums |
| 712120 | Historical Sites |
| 712130 | Zoos and Botanical Gardens |
| 712190 | Nature Parks and Other Similar Institutions |
| 713110 | Amusement and Theme Parks |
| 713120 | Amusement Arcades |
| 713210 | Casinos (except Casino Hotels) |
| 713290 | Other Gambling Industries |
| 713910 | Golf Courses and Country Clubs |
| 713920 | Skiing Facilities |
| 713930 | Marinas |
| 713940 | Fitness and Recreational Sports Centers |
| 713950 | Bowling Centers |
| 713990 | All Other Amusement and Recreation Industries |
## 72 — Accommodation and Food Services
| NAICS Code | Industry Title |
| ---------- | ------------------------------------------------------------ |
| 721110 | Hotels (except Casino Hotels) and Motels |
| 721120 | Casino Hotels |
| 721191 | Bed-and-Breakfast Inns |
| 721199 | All Other Traveler Accommodation |
| 721211 | RV (Recreational Vehicle) Parks and Campgrounds |
| 721214 | Recreational and Vacation Camps (except Campgrounds) |
| 721310 | Rooming and Boarding Houses, Dormitories, and Workers' Camps |
| 722310 | Food Service Contractors |
| 722320 | Caterers |
| 722330 | Mobile Food Services |
| 722410 | Drinking Places (Alcoholic Beverages) |
| 722511 | Full-Service Restaurants |
| 722513 | Limited-Service Restaurants |
| 722514 | Cafeterias, Grill Buffets, and Buffets |
| 722515 | Snack and Nonalcoholic Beverage Bars |
## 81 — Other Services (except Public Administration)
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| 811111 | General Automotive Repair |
| 811114 | Specialized Automotive Repair |
| 811121 | Automotive Body, Paint, and Interior Repair and Maintenance |
| 811122 | Automotive Glass Replacement Shops |
| 811191 | Automotive Oil Change and Lubrication Shops |
| 811192 | Car Washes |
| 811198 | All Other Automotive Repair and Maintenance |
| 811210 | Electronic and Precision Equipment Repair and Maintenance |
| 811310 | Commercial and Industrial Machinery and Equipment (except Automotive and Electronic) Repair and Maintenance |
| 811411 | Home and Garden Equipment Repair and Maintenance |
| 811412 | Appliance Repair and Maintenance |
| 811420 | Reupholstery and Furniture Repair |
| 811430 | Footwear and Leather Goods Repair |
| 811490 | Other Personal and Household Goods Repair and Maintenance |
| 812111 | Barber Shops |
| 812112 | Beauty Salons |
| 812113 | Nail Salons |
| 812191 | Diet and Weight Reducing Centers |
| 812199 | Other Personal Care Services |
| 812210 | Funeral Homes and Funeral Services |
| 812220 | Cemeteries and Crematories |
| 812310 | Coin-Operated Laundries and Drycleaners |
| 812320 | Drycleaning and Laundry Services (except Coin-Operated) |
| 812331 | Linen Supply |
| 812332 | Industrial Launderers |
| 812910 | Pet Care (except Veterinary) Services |
| 812921 | Photofinishing Laboratories (except One-Hour) |
| 812922 | One-Hour Photofinishing |
| 812930 | Parking Lots and Garages |
| 812990 | All Other Personal Services |
| 813110 | Religious Organizations |
| 813211 | Grantmaking Foundations |
| 813212 | Voluntary Health Organizations |
| 813219 | Other Grantmaking and Giving Services |
| 813311 | Human Rights Organizations |
| 813312 | Environment, Conservation and Wildlife Organizations |
| 813319 | Other Social Advocacy Organizations |
| 813410 | Civic and Social Organizations |
| 813910 | Business Associations |
| 813920 | Professional Organizations |
| 813930 | Labor Unions and Similar Labor Organizations |
| 813940 | Political Organizations |
| 813990 | Other Similar Organizations (except Business, Professional, Labor, and Political Organizations) |
| 814110 | Private Households |
## 92 — Public Administration
| NAICS Code | Industry Title |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| 921110 | Executive Offices |
| 921120 | Legislative Bodies |
| 921130 | Public Finance Activities |
| 921140 | Executive and Legislative Offices, Combined |
| 921150 | American Indian and Alaska Native Tribal Governments |
| 921190 | Other General Government Support |
| 922110 | Courts |
| 922120 | Police Protection |
| 922130 | Legal Counsel and Prosecution |
| 922140 | Correctional Institutions |
| 922150 | Parole Offices and Probation Offices |
| 922160 | Fire Protection |
| 922190 | Other Justice, Public Order, and Safety Activities |
| 923110 | Administration of Education Programs |
| 923120 | Administration of Public Health Programs |
| 923130 | Administration of Human Resource Programs (except Education, Public Health, and Veterans' Affairs Programs) |
| 923140 | Administration of Veterans' Affairs |
| 924110 | Administration of Air and Water Resource and Solid Waste Management Programs |
| 924120 | Administration of Conservation Programs |
| 925110 | Administration of Housing Programs |
| 925120 | Administration of Urban Planning and Community and Rural Development |
| 926110 | Administration of General Economic Programs |
| 926120 | Regulation and Administration of Transportation Programs |
| 926130 | Regulation and Administration of Communications, Electric, Gas, and Other Utilities |
| 926140 | Regulation of Agricultural Marketing and Commodities |
| 926150 | Regulation, Licensing, and Inspection of Miscellaneous Commercial Sectors |
| 927110 | Space Research and Technology |
| 928110 | National Security |
| 928120 | International Affairs |
## Related
Sector and subsector reference, plus how NAICS works.
When to filter on `naics_code` versus the other industry filters.
# Understanding NAICS Codes
Source: https://developer.moltsets.com/moltsets-data/understanding-naics-codes
A quick reference for NAICS industry classification codes — what they are, how they're used, and lookup tables for all 20 sectors and their subsectors.
The North American Industry Classification System (NAICS) is the standard used by government agencies and businesses across the US, Canada, and Mexico to classify companies by the type of economic activity they perform. It replaced the older SIC (Standard Industrial Classification) system and is maintained jointly by statistical agencies in all three countries, with a revision cycle every five years (the current version is NAICS 2022).
Each NAICS code is a two-to-six digit number:
* **2 digits** — sector (broadest category, e.g. 54 = Professional, Scientific, and Technical Services)
* **3 digits** — subsector
* **4 digits** — industry group
* **5 digits** — NAICS industry
* **6 digits** — national industry (the most specific level, used for US-specific reporting)
The further right you go, the more specific the classification. A company's NAICS code narrows from a broad sector down to a precise description of what it actually does.
See [Six-Digit NAICS Codes & Titles](/moltsets-data/six-digit-naics-codes-titles) for the comprehensive six-digit national industry list.
## What NAICS codes are used for
NAICS codes are widely used to:
* Segment and filter company data by industry
* Benchmark businesses against others in the same category
* Determine eligibility for government contracts, grants, and loans (e.g. SBA size standards)
* Power targeting and prospecting in B2B sales and marketing
* Standardize industry classification across databases from different sources
Below is the full list of the 20 top-level NAICS sectors. The subsector table for each one follows in [Subsector reference tables](#subsector-reference-tables).
| Code | Sector |
| --------- | ------------------------------------------------------------------------ |
| **11** | Agriculture, Forestry, Fishing and Hunting |
| **21** | Mining, Quarrying, and Oil and Gas Extraction |
| **22** | Utilities |
| **23** | Construction |
| **31-33** | Manufacturing |
| **42** | Wholesale Trade |
| **44-45** | Retail Trade |
| **48-49** | Transportation and Warehousing |
| **51** | Information |
| **52** | Finance and Insurance |
| **53** | Real Estate and Rental and Leasing |
| **54** | Professional, Scientific, and Technical Services |
| **55** | Management of Companies and Enterprises |
| **56** | Administrative and Support and Waste Management and Remediation Services |
| **61** | Educational Services |
| **62** | Health Care and Social Assistance |
| **71** | Arts, Entertainment, and Recreation |
| **72** | Accommodation and Food Services |
| **81** | Other Services (except Public Administration) |
| **92** | Public Administration |
## Where NAICS codes are used in MoltSets
`naics_code` is a filter on the [`search_companies`](/best-practices/searching-for-companies) and [`search_people`](/best-practices/searching-for-people) endpoints.
It matches at any level of the hierarchy, so a 2-digit sector code casts a wide net and a 6-digit code narrows to a precise industry — for example, `"54"` returns all of Professional, Scientific, and Technical Services, while `"541120"` returns only Offices of Notaries.
It's the most standardised of the industry filters available on these endpoints (the others being `industry` and `linkedin_industry`), so it's the one to reach for when you need consistent, well-defined industry boundaries rather than broader category buckets — useful for building prospect lists or contact searches that need to match a specific industry precisely, rather than relying on a loosely-related keyword bucket.
See [Searching for Companies](/best-practices/searching-for-companies) and [Searching for People](/best-practices/searching-for-people) for guidance on when to use `naics_code` versus the other industry filters.
## Subsector reference tables
Each table below lists the 3-digit subsector codes within that sector. These are the next level of detail below the top-level sector code.
### 11 — Agriculture, Forestry, Fishing and Hunting
| Code | Subsector |
| ---- | ----------------------------------------------- |
| 111 | Crop Production |
| 112 | Animal Production and Aquaculture |
| 113 | Forestry and Logging |
| 114 | Fishing, Hunting and Trapping |
| 115 | Support Activities for Agriculture and Forestry |
### 21 — Mining, Quarrying, and Oil and Gas Extraction
| Code | Subsector |
| ---- | ----------------------------- |
| 211 | Oil and Gas Extraction |
| 212 | Mining (except Oil and Gas) |
| 213 | Support Activities for Mining |
### 22 — Utilities
| Code | Subsector |
| ---- | --------- |
| 221 | Utilities |
### 23 — Construction
| Code | Subsector |
| ---- | ---------------------------------------- |
| 236 | Construction of Buildings |
| 237 | Heavy and Civil Engineering Construction |
| 238 | Specialty Trade Contractors |
### 31-33 — Manufacturing
| Code | Subsector |
| ---- | ------------------------------------------------------------ |
| 311 | Food Manufacturing |
| 312 | Beverage and Tobacco Product Manufacturing |
| 313 | Textile Mills |
| 314 | Textile Product Mills |
| 315 | Apparel Manufacturing |
| 316 | Leather and Allied Product Manufacturing |
| 321 | Wood Product Manufacturing |
| 322 | Paper Manufacturing |
| 323 | Printing and Related Support Activities |
| 324 | Petroleum and Coal Products Manufacturing |
| 325 | Chemical Manufacturing |
| 326 | Plastics and Rubber Products Manufacturing |
| 327 | Nonmetallic Mineral Product Manufacturing |
| 331 | Primary Metal Manufacturing |
| 332 | Fabricated Metal Product Manufacturing |
| 333 | Machinery Manufacturing |
| 334 | Computer and Electronic Product Manufacturing |
| 335 | Electrical Equipment, Appliance, and Component Manufacturing |
| 336 | Transportation Equipment Manufacturing |
| 337 | Furniture and Related Product Manufacturing |
| 339 | Miscellaneous Manufacturing |
### 42 — Wholesale Trade
| Code | Subsector |
| ---- | -------------------------------------- |
| 423 | Merchant Wholesalers, Durable Goods |
| 424 | Merchant Wholesalers, Nondurable Goods |
| 425 | Wholesale Trade Agents and Brokers |
### 44-45 — Retail Trade
| Code | Subsector |
| ---- | ---------------------------------------------------------------------------- |
| 441 | Motor Vehicle and Parts Dealers |
| 444 | Building Material and Garden Equipment and Supplies Dealers |
| 445 | Food and Beverage Retailers |
| 449 | Furniture, Home Furnishings, Electronics, and Appliance Retailers |
| 455 | General Merchandise Retailers |
| 456 | Health and Personal Care Retailers |
| 457 | Gasoline Stations and Fuel Dealers |
| 458 | Clothing, Clothing Accessories, Shoe, and Jewelry Retailers |
| 459 | Sporting Goods, Hobby, Musical Instrument, Book, and Miscellaneous Retailers |
### 48-49 — Transportation and Warehousing
| Code | Subsector |
| ---- | ------------------------------------------- |
| 481 | Air Transportation |
| 482 | Rail Transportation |
| 483 | Water Transportation |
| 484 | Truck Transportation |
| 485 | Transit and Ground Passenger Transportation |
| 486 | Pipeline Transportation |
| 487 | Scenic and Sightseeing Transportation |
| 488 | Support Activities for Transportation |
| 491 | Postal Service |
| 492 | Couriers and Messengers |
| 493 | Warehousing and Storage |
### 51 — Information
| Code | Subsector |
| ---- | -------------------------------------------------------------------------------------- |
| 512 | Motion Picture and Sound Recording Industries |
| 513 | Publishing Industries |
| 516 | Broadcasting and Content Providers |
| 517 | Telecommunications |
| 518 | Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services |
| 519 | Web Search Portals, Libraries, Archives, and Other Information Services |
### 52 — Finance and Insurance
| Code | Subsector |
| ---- | --------------------------------------------------------------------------------------- |
| 521 | Monetary Authorities-Central Bank |
| 522 | Credit Intermediation and Related Activities |
| 523 | Securities, Commodity Contracts, and Other Financial Investments and Related Activities |
| 524 | Insurance Carriers and Related Activities |
| 525 | Funds, Trusts, and Other Financial Vehicles |
### 53 — Real Estate and Rental and Leasing
| Code | Subsector |
| ---- | -------------------------------------------------------------------- |
| 531 | Real Estate |
| 532 | Rental and Leasing Services |
| 533 | Lessors of Nonfinancial Intangible Assets (except Copyrighted Works) |
### 54 — Professional, Scientific, and Technical Services
| Code | Subsector |
| ---- | ------------------------------------------------ |
| 541 | Professional, Scientific, and Technical Services |
### 55 — Management of Companies and Enterprises
| Code | Subsector |
| ---- | --------------------------------------- |
| 551 | Management of Companies and Enterprises |
### 56 — Administrative and Support and Waste Management and Remediation Services
| Code | Subsector |
| ---- | ----------------------------------------- |
| 561 | Administrative and Support Services |
| 562 | Waste Management and Remediation Services |
### 61 — Educational Services
| Code | Subsector |
| ---- | -------------------- |
| 611 | Educational Services |
### 62 — Health Care and Social Assistance
| Code | Subsector |
| ---- | --------------------------------------- |
| 621 | Ambulatory Health Care Services |
| 622 | Hospitals |
| 623 | Nursing and Residential Care Facilities |
| 624 | Social Assistance |
### 71 — Arts, Entertainment, and Recreation
| Code | Subsector |
| ---- | --------------------------------------------------------- |
| 711 | Performing Arts, Spectator Sports, and Related Industries |
| 712 | Museums, Historical Sites, and Similar Institutions |
| 713 | Amusement, Gambling, and Recreation Industries |
### 72 — Accommodation and Food Services
| Code | Subsector |
| ---- | --------------------------------- |
| 721 | Accommodation |
| 722 | Food Services and Drinking Places |
### 81 — Other Services (except Public Administration)
| Code | Subsector |
| ---- | ---------------------------------------------------------------------- |
| 811 | Repair and Maintenance |
| 812 | Personal and Laundry Services |
| 813 | Religious, Grantmaking, Civic, Professional, and Similar Organizations |
| 814 | Private Households |
### 92 — Public Administration
| Code | Subsector |
| ---- | ----------------------------------------------------------------------------- |
| 921 | Executive, Legislative, and Other General Government Support |
| 922 | Justice, Public Order, and Safety Activities |
| 923 | Administration of Human Resource Programs |
| 924 | Administration of Environmental Quality Programs |
| 925 | Administration of Housing Programs, Urban Planning, and Community Development |
| 926 | Administration of Economic Programs |
| 927 | Space Research and Technology |
| 928 | National Security and International Affairs |
## Related
The full six-digit national industry list.
When to filter on `naics_code` versus the other industry filters.
# Find Companies and Contacts
Source: https://developer.moltsets.com/use-cases/find-companies-and-contacts
Use MoltSets search to build prospect lists, look up companies by domain, and find contacts matching an ICP — via the MCP or the API.
MoltSets has two search endpoints: one for companies and one for contacts. Both accept the same core filters and return ranked results. Use them when you want to find records matching a profile rather than enrich a specific person or company you already know.
If you already have a LinkedIn URL, email, or IP address and want to enrich it, see [I Have X, I Want Y](/use-cases/i-have-x-i-want-y).
Search results are capped at **25 per call** (`limit` max 25, default 10). **Free-plan accounts are capped at 5 per call** (`limit` max 5) and get 100 search results total, lifetime. Use `limit` and `offset` together to paginate through larger result sets. See [Pagination](#pagination) below for examples.
Neither endpoint supports a founding-year filter. Industry and range filters use fixed enumerations — see the API reference for accepted values.
## Available Filters
The two endpoints share most of their vocabulary. `industry`, `employee_range`, `revenue_range`, `naics_code`, `linkedin_industry`, `country`, `state`, `limit`, and `offset` appear on both; the rest are endpoint-specific.
### `search_companies`
| Filter | What it does | Notes |
| ------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | Free-text search across company name | Do not use for domain, industry, or size — use the dedicated filters for those |
| `domain` | Exact company domain match | Full URLs are normalised automatically (`https://www.acme.com/about` → `acme.com`). Prefer this over `query` when you have a known domain |
| `industry` | Filter by industry | Fixed enumeration — see [Search Company Profiles](/api-reference/search/search-company-profiles) for accepted values |
| `linkedin_industry` | Filter by LinkedIn's industry label | LinkedIn's own vocabulary, hundreds of labels — finer-grained than `industry` |
| `naics_code` | Filter by NAICS industry code | Matches at any hierarchy level — 2-digit sector through 6-digit national industry |
| `employee_range` | Filter by headcount band | Fixed enumeration — see [Search Company Profiles](/api-reference/search/search-company-profiles) for accepted values |
| `revenue_range` | Filter by annual revenue band | Fixed enumeration — see [Search Company Profiles](/api-reference/search/search-company-profiles) for accepted values |
| `country` | Exact country name filter | Company location is team-derived — see the caveat below |
| `state` | Exact state or region filter | Full names, not abbreviations. Combine with `country` |
| `exclude_domain` | Removes specific companies | Your suppression list — pass the accounts you already have. Takes a list |
| `exclude_industry` | Removes whole industries | Same values as `industry`. Takes a list |
| `exclude_employee_range` | Removes headcount bands | Same values as `employee_range`. Takes a list |
| `exclude_revenue_range` | Removes revenue bands | Same values as `revenue_range`. Takes a list |
| `limit` | Number of results to return | Max 25 per call, default 10 (Free plan: max 5) |
| `offset` | Number of results to skip | Use with `limit` to paginate |
Excluded companies are never returned, so they cost you no tokens and no search records — always cheaper than filtering results yourself. Exclusions narrow a search but can't be the whole search: at least one positive input is still required.
`country` and `state` on `search_companies` describe where the company's **team** is based. That's accurate for the small companies that dominate the index, but large multinationals are attributed to a single one of their offices — combine location with other filters rather than relying on it alone for global companies.
### `search_people`
| Filter | What it does | Notes |
| -------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `query` | Free-text search across name, company, title, and headline | Put **names** here. For a job title use `title` instead |
| `title` | Job title filter | The precise way to search by role — matches the title field alone (\~85% filled) |
| `company` | Company name filter | Scopes to the person's employer. Every word you supply must appear in the name (`Acme` matches `Acme Corporation`) |
| `company_domain` | Exact company domain match | Full URLs are normalised automatically. Prefer this over `company` when you have a known domain |
| `country` | Exact country name filter | Most reliable filter (\~99% filled). Must match the stored value |
| `state` | Exact state or region filter | Full names, not abbreviations — `Texas`, not `TX` |
| `city` | Exact city name filter | Matches the exact stored city, not its suburbs. Combine with `state`/`country` to disambiguate |
| `seniority` | Exact seniority level | Fixed enumeration — see [Search Business Profiles](/api-reference/search/search-business-profiles) for accepted values |
| `industry` | Filter by industry | Fixed enumeration — see the API reference for accepted values |
| `linkedin_industry` | Filter by LinkedIn's industry label | Hundreds of labels, finer-grained than `industry` |
| `naics_code` | Filter by NAICS industry code | Matches at any hierarchy level |
| `department` / `functional_area` | Team or function filter | Co-populated from the same data — use one or the other, never both |
| `employee_range` | Filter by employer headcount band | Applies to the person's **current employer** |
| `revenue_range` | Filter by employer revenue band | Applies to the person's **current employer** |
| `exclude_company_domain` | Removes people at specific companies | Your suppression list — pass the accounts you already have. Takes a list |
| `exclude_country` | Removes whole countries | Same values as `country`. Takes a list |
| `exclude_state` | Removes states or regions | Same values as `state`. Takes a list |
| `exclude_industry` | Removes whole industries | Same values as `industry`. Takes a list |
| `exclude_seniority` | Removes seniority levels | Same values as `seniority`. Takes a list |
| `exclude_employee_range` | Removes employer size bands | Same values as `employee_range`. Takes a list |
| `limit` | Number of results to return | Max 25 per call, default 10 (Free plan: max 5) |
| `offset` | Number of results to skip | Use with `limit` to paginate |
Combine `query` with filters for best precision — filters cost nothing extra to attach, and a search built from filters alone runs far cheaper than one driven by free text. See [Searching for People](/best-practices/searching-for-people) and [Searching for Companies](/best-practices/searching-for-companies) for the full guidance.
Results are ranked by relevance — higher `_score` means a stronger match.
## Finding Companies
Use `search_companies` when your output is a list of companies. Returns name, domain, industry, employee count and range, revenue range, LinkedIn URL, city/state/country, NAICS codes and titles, LinkedIn industry, and logo URL.
| I want… | Type in Claude… | Filters used |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| A specific company by domain | Find the company record for acme.com | `domain` |
| Companies matching a name | Find company profiles matching Acme | `query` |
| Companies in a specific industry | Find information technology companies | `industry` |
| Companies by industry and headcount | Find information technology companies with 51–200 employees | `industry`, `employee_range` |
| Companies by industry and revenue | Find computer software companies with revenue above \$50M | `industry`, `revenue_range` |
| Companies matching an ICP | Find privately held computer software companies with 201–500 employees and revenue between $10M and $50M | `industry`, `employee_range`, `revenue_range` |
| Companies minus the ones you have | Find information technology companies with 51–200 employees, but not acme.com or stripe.com | `industry`, `employee_range`, `exclude_domain` |
| Companies minus a segment | Find software companies but skip anyone under 21 employees | `industry`, `exclude_employee_range` |
## Finding Contacts
Use `search_people` when your output is a list of people. Returns name, title, seniority, location, LinkedIn URL, business email with its risk score and validation date, and a nested company object carrying domain, size, industry, NAICS codes, and logo URL.
| I want… | Type in Claude… | Filters used |
| ------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- |
| All contacts at a specific company | Find contacts at acme.com | `company_domain` |
| Contacts in a specific role | Find account executives in the United States | `title`, `country` |
| Contacts at a named company | Find contacts at Acme | `company` |
| Contacts in a specific industry | Find contacts at information technology companies | `industry` |
| Decision-makers at a company | Find senior contacts at acme.com | `company_domain`, `seniority` |
| Contacts in a specific team | Find engineering contacts at acme.com | `company_domain`, `department` |
| Contacts in an industry and country | Find marketing contacts at software companies in the United States | `industry`, `country` |
| Contacts in a specific city | Find sales contacts in Austin, Texas | `city`, `state` |
| Contacts at companies of a given size | Find VPs at companies with 51–200 employees | `seniority`, `employee_range` |
| Contacts matching an ICP | Find senior engineering contacts at information technology companies in the United States | `industry`, `seniority`, `department`, `country` |
| Contacts minus the accounts you have | Find VPs at software companies, but not at acme.com or stripe.com | `industry`, `seniority`, `exclude_company_domain` |
| Contacts anywhere but one region | Find sales contacts in the United States outside California | `country`, `exclude_state` |
To target contacts by **company size or revenue**, filter directly on `search_people` — `employee_range` and `revenue_range` apply to the person's current employer, so you can find people at companies of a given size without naming a company. Chain through `search_companies` only when you also want the company records themselves.
## Pagination
Each call returns a maximum of 25 results (5 on the Free plan). To pull more, increment `offset` by 25 on each subsequent call (5 on the Free plan). Free-plan accounts have a lifetime cap of 100 search results total, so pagination is only useful up to that ceiling.
The total number of matching records is returned in the `total` field on every response — use this to determine how many pages exist before you start paginating.
## Using with MCP
Once MoltSets is connected to Claude, describe what you want and Claude will call the right search endpoint with the right filters.
**Exact company lookup**
```
Look up the company record for acme.com
```
**ICP company list**
```
Find computer software companies with 51–200 employees and revenue between $10M and $50M
```
**ICP contact list**
```
Find senior contacts at information technology companies in the United States
```
**Paginated pull**
```
Find senior contacts at information technology companies in the United States. Get the first 25, then keep fetching the next page until you have 100 results.
```
**Paginated offset/skip**
```
Find senior contacts at information technology companies in the United States. Offset by 50 then keep fetching the next page until you have 100 additional results.
```
## Using with the API
All search requests follow the same shape. Pass your filters in the request body and increment `offset` to paginate.
**Find companies matching an ICP**
```javascript theme={null}
const response = await fetch("https://api.moltsets.com/api/v1/tools/search_companies", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
industry: "Information Technology",
employee_range: "51-200",
revenue_range: "$10M - $20M",
limit: 25,
offset: 0
})
});
const data = await response.json();
// data.status — "ok" on a hit, "not_found" when nothing matched (still HTTP 200)
// data.results.results — array of matching companies
// data.results.total — total matching records across all pages
```
**Find contacts at a specific company**
```javascript theme={null}
const response = await fetch("https://api.moltsets.com/api/v1/tools/search_people", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
company_domain: "acme.com",
limit: 25,
offset: 0
})
});
const data = await response.json();
// data.results.results — array of matching contacts
// data.results.total — total matching records across all pages
```
**Paginating through results**
`total` stops counting at 10,000. A `total` of `10000` means *at least* 10,000 matches, not exactly 10,000 — don't plan a pull off it. `offset + limit` is capped at 10,000 too, so paging can't reach record 10,001. For a larger list, split the search into narrower slices and walk each one separately.
```javascript theme={null}
async function fetchAllResults(filters, endpoint) {
const results = [];
let offset = 0;
const limit = 25;
while (true) {
const response = await fetch(`https://api.moltsets.com/api/v1/tools/${endpoint}`, {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({ ...filters, limit, offset })
});
const data = await response.json();
// A search that matches nothing is a normal 200 with status "not_found"
if (data.status === "not_found") break;
const page = data.results.results;
results.push(...page);
if (results.length >= data.results.total || page.length < limit) break;
offset += limit;
// `offset + limit` can't exceed 10,000 — the search window is capped there
if (offset + limit > 10000) break;
}
return results;
}
// Example: fetch all contacts at acme.com
// note: search_people scopes by `company_domain`; `domain` is the search_companies filter
const contacts = await fetchAllResults({ company_domain: "acme.com" }, "search_people");
```
# I Have X, I Want Y
Source: https://developer.moltsets.com/use-cases/i-have-x-i-want-y
Find the right MoltSets tool based on what data you have and what you need. Covers email finding, phone lookup, people finding, and company search.
## Before You Begin
The examples in this guide are designed for use with the MoltSets MCP (Model Context Protocol) server connected to Claude or another AI agent. The "Type in Claude" prompts will only work once your AI tool is connected to MoltSets — without it, Claude has no access to MoltSets tools or your account data.
If you haven't set that up yet, [connect your AI agent to the MoltSets MCP](/integrations/moltsets-mcp) before proceeding.
***
Pick your starting point below. Each table shows what input you need, what you'll get back, an example prompt to use in Claude, and the tool name.
## Search
Search MoltSets's company and contact database by name, domain, industry, employee count, or revenue range. Use these endpoints to build B2B prospect lists, identify target accounts, and find contacts that match your ideal customer profile.
| I have… | I want… | Type in Claude… | Tool |
| ----------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------ |
| Company name | Matching company profiles (name, domain, industry, size, revenue) | Find company profiles matching Acme | `search_companies` |
| Domain | Exact company record | Look up the company at acme.com | `search_companies` |
| Industry + employee size or revenue range | Filtered list of companies | Find information technology companies with 51-200 employees | `search_companies` |
| Company name or domain | All contacts at that company | Find contacts at acme.com | `search_people` |
| Company name + industry filter | Contacts filtered by industry | Find information technology contacts at acme.com | `search_people` |
| Company + seniority | Decision-makers at a company | Find senior contacts at acme.com | `search_people` |
| Industry + country | Contacts in an industry and country | Find marketing contacts at software companies in the United States | `search_people` |
| Company + department or function | Contacts in a specific team | Find engineering contacts at acme.com | `search_people` |
`search_people` filters on `query`, `title`, `company`, `company_domain`, `country`, `state`, `city`, `seniority`, `industry`, `department`, `functional_area`, `naics_code`, `linkedin_industry`, `employee_range`, and `revenue_range`, plus six `exclude_*` filters. `employee_range` and `revenue_range` apply to the person's **current employer**, so you can target contacts by company size or revenue in a single call — no need to run `search_companies` first and fan out over its domains.
\| Person name + company domain | LinkedIn slug for that person | Find the LinkedIn profile for John Smith at acme.com | `search_linkedin_profile` |
\| Person name + company domain | Result count before spending tokens | How many people named John Smith are at acme.com | `search_linkedin_profile` (`count_only: true`) |
\| Person name + company domain | Verified business email in one call (plus matched LinkedIn URL) | Find the business email for John Smith at acme.com | `search_business_email_by_name` |
\| Person name + company domain | Full business profile in one call (company, title, firmographics) | Find the business profile for John Smith at acme.com | `search_business_profile_by_name` |
## Get Verified Emails
Resolve LinkedIn profile URLs and company domains into verified business and personal email addresses. Supports single lookups and multi-step chains for building outbound contact lists with high deliverability.
| I have… | I want… | Type in Claude… | Tool |
| ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| LinkedIn URL | Best available email (business if found, falls back to personal) | Find the best email for linkedin.com/in/username | `linkedin_to_best_email` |
| LinkedIn URL | Business email only | Find the business email for linkedin.com/in/username | `linkedin_to_business_email` |
| LinkedIn URL | Personal email only | Find the personal email for linkedin.com/in/username | `linkedin_to_personal_email` \* |
| LinkedIn URL | Best personal email | Find the best personal email for linkedin.com/in/username | `linkedin_to_best_personal_email` \* |
| Company name or domain | Best available email for each employee | Search for employees at acme.com and get their best email address | `search_people` → `linkedin_to_best_email` |
| Company name or domain | Business emails for each employee | Search for employees at acme.com and get their business email addresses | `search_people` → `linkedin_to_business_email` |
| Company name or domain | Personal emails for each employee | Search for employees at acme.com and get their personal email addresses | `search_people` → `linkedin_to_personal_email` \* |
| Person name + company domain | Best email for that person | Find John Smith at acme.com and get their best email | `search_linkedin_profile` → `linkedin_to_best_email` |
| LinkedIn URL | Business email, falling back to personal if not found | Try to find the business email for linkedin.com/in/username, fall back to personal if nothing is found | `linkedin_to_business_email` → `linkedin_to_personal_email` \* |
\* `linkedin_to_personal_email` and `linkedin_to_best_personal_email` are **not available on every plan** — access is set per account, not by price tier. Call `get_account` and read `personal_email_available` to know where yours stands. Without access, use `linkedin_to_business_email` instead.
Calls from an account without access return **403** with:
```json theme={null}
{
"error": {
"code": "plan_restricted",
"message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
}
}
```
Contact [support@moltsets.com](mailto:support@moltsets.com) to request access.
## Get Carrier-Verified Mobile Phones
Look up carrier-verified mobile phone numbers from LinkedIn profiles and company domains. Every number returned is a real mobile device — no landlines or VoIP. Supports single lookups and batches of up to 100 profiles at once, as well as multi-step chains for building call and SMS lists directly from a company name.
| I have… | I want… | Type in Claude… | Tool |
| --------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| LinkedIn URL | Mobile phone number | Find the mobile phone number for linkedin.com/in/username | `linkedin_to_mobile_phone` |
| List of LinkedIn URLs (up to 100) | Mobile phone numbers for each profile | Find mobile phone numbers for these LinkedIn profiles: \[list] | `linkedin_to_mobile_phone` |
| Company name or domain | Mobile phone numbers for each employee | Search for employees at acme.com and get their mobile phone numbers | `search_people` → `linkedin_to_mobile_phone` |
| Company name + seniority or role filter | Mobile phones for decision-makers at a company | Search for senior contacts at acme.com and get their mobile phone numbers | `search_people` → `linkedin_to_mobile_phone` |
| Person name + company domain | Mobile phone for that person | Find John Smith at acme.com and get their mobile phone number | `search_linkedin_profile` → `linkedin_to_mobile_phone` |
| LinkedIn URL | Email address and mobile phone | Get the email address and mobile phone number for linkedin.com/in/username | `linkedin_to_best_email` + `linkedin_to_mobile_phone` |
MoltSets does **not** currently provide Do Not Call (DNC) status. A returned number is not a number cleared to call — scrub against the applicable registries before you dial or send. See [Getting Carrier-Verified Mobile Phones](/best-practices/getting-carrier-verified-mobile-phones).
## Reverse Lookups
Resolve a single identifier — an email address or a LinkedIn URL — into a complete business profile in one call. Returns name, job title, seniority, company, firmographic data, and emails on file. Use these to enrich inbound leads, form fills, or existing CRM records.
| I have… | I want… | Type in Claude… | Tool |
| ------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------- |
| Email | Full business profile (name, title, company, firmographics) | Look up the business profile for [john@acme.com](mailto:john@acme.com) | `reverse_email_lookup` |
| LinkedIn URL | Complete profile (title, company, industry, revenue, business + personal email) | Get the full profile for linkedin.com/in/username | `reverse_linkedin_lookup` |
## Common Workflows
Some tasks require chaining two tools together. These are the most useful combinations.
### Person name to mobile phone
`search_linkedin_profile` → `linkedin_to_mobile_phone`
You have a person's name and their company domain but no LinkedIn URL. Resolve them to a LinkedIn slug first, then use that to get a mobile phone number.
"Find John Smith at acme.com, then get their mobile phone number."
***
### Company domain to outbound email list
`search_people` → `linkedin_to_best_email`
You have a target company and want a list of contacts with their best email addresses. Search for employees at the company, then enrich each with their best available email.
"Search for employees at acme.com and get their best email address."
***
### Company size or revenue to contact list
`search_companies` → `search_people`
`search_people` can't filter by company size or revenue directly. Find the companies that match those firmographics first, then pull contacts from each matching domain.
"Find computer software companies with 201–500 employees, then get contacts at each one."
***
Not sure where to start? Tell Claude what you have and what you need, and it will pick the right tool automatically.