{
"openapi": "3.1.0",
"info": {
"title": "MoltSets API",
"version": "1.0.0",
"description": "MoltSets is an identity resolution API. Use it to resolve emails, LinkedIn profiles, and IP addresses into enriched contact and company data, including business and personal emails, mobile phone numbers, and firmographic details."
},
"servers": [
{
"url": "https://api.moltsets.com/api/v1/tools",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Pass your API key as a Bearer token. Keys follow the format `ms_XXXXXXXXXXX`."
}
},
"parameters": {
"UserAgentHeader": {
"name": "User-Agent",
"in": "header",
"required": true,
"description": "Identifies the calling client. Any non-empty value is accepted — MoltSets does not validate its contents. Requests without this header are rejected with `403 Forbidden` (`error.code`: `forbidden`).",
"schema": {
"type": "string"
},
"example": "YOUR_APP_NAME/1.0"
}
},
"schemas": {
"Metadata": {
"type": "object",
"properties": {
"fair_use": {
"type": "object",
"description": "Fair Use Policy headroom for the record limits that apply to this call.",
"properties": {
"records_remaining_5h": {
"type": "integer",
"description": "Records you can still request in the current rolling 5-hour window."
},
"records_reset_5h": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the 5-hour records window resets."
},
"records_remaining_1w": {
"type": "integer",
"description": "Records you can still request in the current rolling 1-week window."
},
"records_reset_1w": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the 1-week records window resets."
}
}
},
"tokens_used": {
"type": "integer",
"description": "Tokens consumed by this call. `0` on a `not_found`. Present on token-bound (free) accounts only — accounts on an unlimited subscription omit it."
},
"tokens_remaining": {
"type": "integer",
"description": "Token balance after this call. Present on token-bound (free) accounts only."
},
"personal_email_restricted": {
"type": "boolean",
"description": "Present and `true` only when the call actually withheld personal-email data because the account does not have the personal-email surface. Read a missing personal email as a plan boundary, not as absent data."
},
"identity_hashes_restricted": {
"type": "boolean",
"description": "Present and `true` only when the call stripped `business_email_sha256s` because the account is on the \\$397 or \\$997 plan. Read a missing SHA256 hash as a plan boundary, not as absent data."
},
"retry_after": {
"type": "integer",
"description": "Seconds until the binding Fair Use window unlocks. Present on Fair Use 429s, and on a batch that returned partial results because items were dropped for Fair Use — the same value is sent as a `Retry-After` header."
},
"phone_tokens_used": {
"type": "integer",
"description": "Phone tokens consumed by this call. `linkedin_to_mobile_phone` only; `0` on a `not_found`."
},
"phone_tokens_remaining": {
"type": "integer",
"description": "Phone tokens remaining after this call. `linkedin_to_mobile_phone` only."
}
},
"description": "Per-call metadata. `fair_use` is always present on a tool call; the remaining fields appear only where they apply."
},
"ErrorInvalidInput": {
"type": "object",
"description": "The request body is malformed, or a parameter is missing, malformed, or outside its allowed values.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "invalid_input"
},
"message": {
"type": "string",
"example": "Message describing the nature of the invalid input."
}
}
}
}
},
"ErrorUnauthorized": {
"type": "object",
"description": "The API key or OAuth token is missing, invalid, or revoked.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "unauthorized"
},
"message": {
"type": "string",
"example": "Invalid API key."
}
}
}
}
},
"ErrorInternal": {
"type": "object",
"description": "Returned when the call could not complete — usually because the endpoint is unavailable, though an oversized request can also cause it. Retry with a smaller request first. Never charged.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "internal_error"
},
"message": {
"type": "string",
"example": "Unexpected connection error."
}
}
},
"metadata": {
"type": "object",
"example": {}
}
}
},
"ErrorPlanRestricted": {
"type": "object",
"description": "The request is refused. `forbidden` means the request has no `User-Agent` header — add one (any non-empty value). `plan_restricted` means the tool is not part of the account's plan — today, the dedicated personal-email tools on a plan without the personal-email surface, and the ad-audience tools (`email_to_maid`, `business_email_to_sha256`, `linkedin_to_sha256`) on the \\$397 and \\$997 plans. It is a plan condition, so there is no `Retry-After` and topping up tokens does not clear it. `account_inactive` means the account itself is not active — log in and subscribe to a plan.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "plan_restricted"
},
"message": {
"type": "string",
"example": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
}
}
}
}
},
"ErrorNotFound": {
"type": "object",
"description": "Returned only when the tool name in the URL does not exist or has been retired. A lookup that finds no data is **not** a 404 — it returns HTTP 200 with `status: \"not_found\"`.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "tool_not_found"
},
"message": {
"type": "string",
"example": "Unknown tool name."
}
}
}
}
},
"ErrorRateLimit": {
"type": "object",
"description": "Rate or Fair Use limit. `rate_limited` is the burst/IP guard; `fair_use_limit_exceeded` means a Fair Use **record** window is exhausted (or, on the free tier, the one-time search trial); `fair_use_requests_exceeded` means the 5-hour **request** window is exhausted; `search_concurrency_exceeded` means too many `search_people` / `search_companies` calls are running at the same time for the plan (Free and $27: 3, $97: 5, $397 and $997: 8). The Fair Use codes carry `metadata.retry_after` and a `Retry-After` header. `search_concurrency_exceeded` carries `Retry-After: 1` — retry after 1 second and run fewer searches in parallel.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "fair_use_limit_exceeded"
},
"message": {
"type": "string",
"example": "Fair use record limit reached. Retry after the window resets."
}
}
},
"metadata": {
"type": "object",
"properties": {
"retry_after": {
"type": "integer",
"description": "Seconds until the binding window unlocks. Also sent as a `Retry-After` header. Absent when the limit is a plan condition rather than a window (free-tier search trial exhausted)."
}
}
}
}
},
"ErrorInsufficientTokens": {
"type": "object",
"description": "Out of credit. `insufficient_tokens` means the token balance cannot cover the call; `insufficient_phone_tokens` means the phone token balance (from the separate phone token subscription) cannot cover a mobile-phone result. On a batch, unaffordable items are dropped and the response returns partial results with this error block rather than failing the whole call.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "insufficient_tokens"
},
"message": {
"type": "string",
"example": "You have 0 tokens remaining."
}
}
}
}
},
"ErrorForbidden": {
"type": "object",
"description": "The request has no `User-Agent` header. Add one — any non-empty value is accepted.",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "forbidden"
},
"message": {
"type": "string"
}
}
}
}
}
}
},
"paths": {
"/search_people": {
"post": {
"summary": "Search for People",
"operationId": "searchBusinessProfiles",
"description": "The People Search API lets you search MoltSets' contact database for people by name, job title, company, industry, country, seniority, or department.\n\nUse `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.\n\nEvery positive filter accepts either a single value or a list of values. A list is OR within its field and AND across fields, so `title: [\"CEO\", \"CMO\"]` with `country: [\"United States\", \"Canada\"]` means (CEO or CMO) in (United States or Canada) — one search instead of one per value, with every match ranked together.\n\nThe `exclude_*` parameters (`exclude_company_domain`, `exclude_country`, `exclude_state`, `exclude_industry`, `exclude_seniority`, `exclude_employee_range`) work the other way round: each one also takes a list, but 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.\n\n**Use this endpoint to:**\n- Build targeted lead lists for outbound sales\n- Identify decision makers at specific target accounts\n- Populate outbound sequences with verified contact data\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Search.\n\n**Outcomes:**\nA 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.",
"tags": [
"Search"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Full-text search across full_name, first_name, last_name, company name, title (~85% filled), and headline (~65% filled) using cross-field matching. Multi-word queries distribute terms across fields — \"John Smith\" matches first_name: John AND last_name: Smith rather than requiring either field alone to contain the full string. Best for person names, and for loose natural-language phrases when nothing more specific fits. For a job title or role, use the `title` filter instead: a role placed here is diluted across names and company names and only needs most of its terms to match, so \"Account Executive\" in `query` can also return Account Managers. Likewise use `seniority` for level (VP, Director, C-suite), and `company` or `company_domain` for a specific employer. Categorical values like country or seniority belong in their own filter params rather than this field.",
"example": "Jane Doe"
},
"title": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Job title filter (~85% filled) — scopes results to people whose job title matches, and the precise way to search by role. The match is analysed rather than literal: a one or two word title requires every word, so \"Account Executive\" will not return Account Managers. A longer title requires 75% of its words, rounded down — a three or four word title must match all but one, a five or six word title all but two. That allowance is what stops function words breaking a match, so \"VP of Sales\" still finds \"VP, Sales\". Extra words in the stored title are always fine: \"Account Executive\" matches \"Senior Account Executive, SMB\". Prefer this over putting a role in `query`. For seniority level use the `seniority` filter, which is a clean enumerated list, and use `title` for the role or function itself — the two combine, e.g. `title: \"Sales\"` with `seniority: \"VP\"`. Around 15% of profiles carry no title at all, and those can never match a title filter. Accepts a single value or a list — a list matches any of its values (OR), so `title: [\"CEO\", \"CMO\"]` returns records matching either.",
"example": "Account Executive"
},
"company": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Company name filter — scopes results to people whose employer's name matches. Analysed match: every word you provide must appear in the company name, so extra words in the stored name are fine (\"Acme\" matches \"Acme Corporation\"). Use this when you have a company name but not its domain; if you have the domain, prefer `company_domain`, which is more precise. Accepts a single value or a list — a list matches any of its values (OR), so `company: [\"Acme\", \"Globex\"]` returns records matching either.",
"example": "MoltSets"
},
"company_domain": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
}
],
"description": "Company domain filter — scopes results to people at the company with this website domain. Full URLs are normalised automatically (\"https://www.acme.com/about\" → \"acme.com\"), so there is no need to strip the protocol or path yourself. The most precise way to target a single company — prefer it over `company` whenever you know the domain. Accepts a single value or a list — a list matches any of its values (OR), so `company_domain: [\"acme.com\", \"stripe.com\"]` returns records matching either. A list can hold up to 100 domains.",
"example": "moltsets.com"
},
"country": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact country name filter (~99% filled — most reliable filter). Must match the stored value exactly. Top values by volume: \"United States\", \"India\", \"United Kingdom\", \"Brazil\", \"Canada\", \"France\", \"Mexico\", \"Australia\", \"China\", \"Spain\", \"Netherlands\", \"Italy\", \"Indonesia\", \"Germany\", \"Philippines\", \"Turkey\", \"South Africa\", \"Saudi Arabia\", \"Argentina\", \"Singapore\", \"United Arab Emirates\", \"Colombia\", \"South Korea\", \"Malaysia\", \"Poland\", \"Belgium\", \"Switzerland\", \"Ireland\", \"Sweden\", \"Denmark\", \"Norway\", \"Austria\", \"Portugal\", \"Israel\", \"New Zealand\", \"Finland\", \"Greece\", \"Hungary\", \"Romania\", \"Ukraine\". Use the full English country name. \"UK\" and \"HK\" also exist in the data as dirty values — prefer \"United Kingdom\" and \"Hong Kong\". Accepts a single value or a list — a list matches any of its values (OR), so `country: [\"United States\", \"Canada\"]` returns records matching either.",
"example": "United States"
},
"state": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact state or region name filter on the person's location. Accepts the full name with standard capitalisation or its abbreviation — \"Texas\" and \"TX\" both work. Canadian provinces match by their two-letter code too — \"Ontario\" or \"ON\", \"British Columbia\" or \"BC\", \"Quebec\" or \"QC\". Combine with `country` for precision. Accepts a single value or a list — a list matches any of its values (OR), so `state: [\"Texas\", \"Florida\"]` returns records matching either.",
"example": "Texas"
},
"city": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact city name filter on the person's location. Must match the stored value exactly, with standard capitalisation. City names repeat across regions, so combine with `state` and/or `country` to disambiguate — e.g. city: \"Portland\", state: \"Oregon\". Matches only the exact stored city, not its suburbs — for a metro-area search prefer `state` or `country`. Accepts a single value or a list — a list matches any of its values (OR), so `city: [\"Austin\", \"Dallas\"]` returns records matching either.",
"example": "Austin"
},
"seniority": {
"oneOf": [
{
"type": "string",
"enum": [
"Intern",
"Entry",
"Senior",
"Manager",
"Director",
"VP",
"Head",
"C Suite",
"Owner",
"Partner"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Intern",
"Entry",
"Senior",
"Manager",
"Director",
"VP",
"Head",
"C Suite",
"Owner",
"Partner"
]
}
}
],
"description": "Exact seniority level filter (~60% filled). Must match one of the enumerated values exactly, including the space in \"C Suite\" (not a hyphen). Accepts a single value or a list — a list matches any of its values (OR), so `seniority: [\"VP\", \"C Suite\"]` returns records matching either."
},
"industry": {
"oneOf": [
{
"type": "string",
"enum": [
"Professional and Business Services",
"Information Technology",
"Manufacturing",
"Retail",
"Health and Pharmaceuticals",
"Creative Arts and Entertainment",
"Construction",
"Marketing & Advertising",
"Finance and Banking",
"Tourism and Hospitality",
"Non-Profit and Social Services",
"Food and Beverage",
"Real Estate",
"Education",
"Transportation and Logistics",
"Media and Publishing",
"Energy",
"Government and Public Administration",
"Automotive",
"Telecommunications",
"Agriculture",
"Utilities"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Professional and Business Services",
"Information Technology",
"Manufacturing",
"Retail",
"Health and Pharmaceuticals",
"Creative Arts and Entertainment",
"Construction",
"Marketing & Advertising",
"Finance and Banking",
"Tourism and Hospitality",
"Non-Profit and Social Services",
"Food and Beverage",
"Real Estate",
"Education",
"Transportation and Logistics",
"Media and Publishing",
"Energy",
"Government and Public Administration",
"Automotive",
"Telecommunications",
"Agriculture",
"Utilities"
]
}
}
],
"description": "Exact current industry filter (~60% filled). These 22 buckets are the only supported values, and must match exactly, including capitalisation and punctuation (e.g. the ampersand in \"Marketing & Advertising\"). Accepts a single value or a list — a list matches any of its values (OR), so `industry: [\"Information Technology\", \"Finance and Banking\"]` returns records matching either."
},
"department": {
"oneOf": [
{
"type": "string",
"enum": [
"Operations",
"Sales",
"Information Technology",
"Education",
"Engineering",
"Finance",
"Medical & Health",
"Marketing",
"Human Resources",
"Design",
"Consulting",
"Legal"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Operations",
"Sales",
"Information Technology",
"Education",
"Engineering",
"Finance",
"Medical & Health",
"Marketing",
"Human Resources",
"Design",
"Consulting",
"Legal"
]
}
}
],
"description": "Exact department filter (~60% filled). Shares its underlying data with `functional_area` — use one or the other, not both. Must match one of the enumerated values exactly, including capitalisation and punctuation (e.g. the ampersand in \"Medical & Health\"). Accepts a single value or a list — a list matches any of its values (OR), so `department: [\"Sales\", \"Marketing\"]` returns records matching either."
},
"functional_area": {
"oneOf": [
{
"type": "string",
"enum": [
"Operations",
"Sales",
"Information Technology",
"Education",
"Engineering",
"Finance",
"Medical & Health",
"Marketing",
"Human Resources",
"Design",
"Consulting",
"Legal"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Operations",
"Sales",
"Information Technology",
"Education",
"Engineering",
"Finance",
"Medical & Health",
"Marketing",
"Human Resources",
"Design",
"Consulting",
"Legal"
]
}
}
],
"description": "Exact functional area filter (~60% filled). Shares its underlying data with `department` — use one or the other, not both. Accepts a single value or a list — a list matches any of its values (OR), so `functional_area: [\"Sales\", \"Marketing\"]` returns records matching either."
},
"employee_range": {
"oneOf": [
{
"type": "string",
"enum": [
"1-10",
"11-20",
"21-50",
"51-200",
"201-500",
"501-1000",
"1001-5000",
"5001+"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"1-10",
"11-20",
"21-50",
"51-200",
"201-500",
"501-1000",
"1001-5000",
"5001+"
]
}
}
],
"description": "Exact employee-count range filter on the person's current employer — finds people at companies of a certain size without needing to name a specific company. These eight numeric bands are the only supported values, and use the same vocabulary as `search_companies`. Combine with other filters, e.g. `seniority: \"VP\"`, `employee_range: \"51-200\"`. Accepts a single value or a list — a list matches any of its values (OR), so `employee_range: [\"51-200\", \"201-500\"]` returns records matching either."
},
"revenue_range": {
"oneOf": [
{
"type": "string",
"enum": [
"Below $500k",
"$500k - $1M",
"$1M - $5M",
"$5M - $10M",
"$10M - $20M",
"$20M - $50M",
"Above $50M"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Below $500k",
"$500k - $1M",
"$1M - $5M",
"$5M - $10M",
"$10M - $20M",
"$20M - $50M",
"Above $50M"
]
}
}
],
"description": "Exact annual revenue range filter on the person's current employer — finds people at companies of a certain revenue without needing to name a specific company. These seven bands are the only supported values, and use the same vocabulary as `search_companies`. \"Above $50M\" is a flat catch-all for all revenue over $50M; there is no finer band above it. Accepts a single value or a list — a list matches any of its values (OR), so `revenue_range: [\"$10M - $20M\", \"$20M - $50M\"]` returns records matching either."
},
"naics_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact NAICS industry code filter on the person's current employer (~50% filled). Works at any level of the hierarchy, from the 2-digit sector (\"23\" = Construction, \"54\" = Professional Services) through to the 6-digit national industry (\"541120\" = Offices of Notaries, \"511210\" = Software Publishers). Use a short code for broad industry targeting and a longer code for precision. The most standardised industry filter available — prefer it over `industry` when you need fine-grained targeting. Accepts a single value or a list — a list matches any of its values (OR), so `naics_code: [\"5112\", \"5415\"]` returns records matching either.",
"example": "541120"
},
"linkedin_industry": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact LinkedIn industry label filter on the person's current employer. Uses LinkedIn's own industry vocabulary, which is far finer-grained than the 22 buckets in `industry`. Must match the stored label exactly, with standard capitalisation — for example \"Software Development\", \"Hospitality\", \"Legal Services\", \"Wellness and Fitness Services\", \"Construction\", \"Staffing and Recruiting\". Use when a niche industry cannot be expressed by the broad `industry` buckets. Accepts a single value or a list — a list matches any of its values (OR), so `linkedin_industry: [\"Software Development\", \"IT Services and IT Consulting\"]` returns records matching either.",
"example": "Software Development"
},
"exclude_company_domain": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Company domains to exclude. People at any listed company are dropped from the results — this is the suppression list, so pass the accounts you already have (existing customers, current vendors, your own company) and they never come back. Full URLs are normalised automatically, exactly as with `company_domain`. Excluded records cost you nothing: they consume no tokens and no fair use records, so excluding here is always cheaper than filtering the results yourself. A list can hold up to 100 domains.",
"example": [
"acme.com",
"stripe.com"
]
},
"exclude_country": {
"type": "array",
"items": {
"type": "string"
},
"description": "Countries to exclude. People in any listed country are dropped. Accepts the same values as `country` — use it when you want everywhere except a few places.",
"example": [
"India",
"Philippines"
]
},
"exclude_state": {
"type": "array",
"items": {
"type": "string"
},
"description": "States or regions to exclude. People in any listed state are dropped. Accepts the same values as `state` (full names or abbreviations). Combine with a positive `country` — for example `country: \"United States\"` with `exclude_state: [\"California\"]`.",
"example": [
"California",
"New York"
]
},
"exclude_industry": {
"type": "array",
"items": {
"type": "string"
},
"description": "Industries to exclude. People whose current industry is any listed value are dropped. Accepts the same values as `industry`. Around 40% of profiles carry no industry at all, and exclusion only removes profiles that positively carry a listed value — so those profiles still appear.",
"example": [
"Education",
"Government and Public Administration"
]
},
"exclude_seniority": {
"type": "array",
"items": {
"type": "string"
},
"description": "Seniority levels to exclude. People at any listed level are dropped. Accepts the same values as `seniority` (note the space in \"C Suite\"). Same caveat as `exclude_industry`: profiles with no seniority on record are not excluded.",
"example": [
"Intern",
"Entry"
]
},
"exclude_employee_range": {
"type": "array",
"items": {
"type": "string"
},
"description": "Employer size bands to exclude. People at companies in any listed band are dropped. Accepts the same values as `employee_range` — for example [\"1-10\", \"11-20\"] to skip very small companies, or [\"5001+\"] to skip enterprises.",
"example": [
"1-10",
"11-20"
]
},
"limit": {
"type": "integer",
"description": "Number of results to return (default: 10, max: 25).",
"default": 10,
"minimum": 1,
"maximum": 25
},
"offset": {
"type": "integer",
"description": "Number of results to skip for pagination (default: 0). Use with limit to page through results — e.g. offset: 10 to get the second page of 10 results.",
"default": 0
}
}
},
"example": {
"title": "Account Executive",
"country": [
"United States",
"Canada"
],
"seniority": "Senior",
"exclude_company_domain": [
"acme.com",
"stripe.com"
],
"limit": 10,
"offset": 0
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"results": [
{
"full_name": "Morgan Hebb",
"first_name": "Morgan",
"last_name": "Hebb",
"title": "Account Executive",
"headline": "EdTech | Account Executive | Teacher by Training",
"seniority": "Senior",
"city": "Chicago",
"state": "Illinois",
"country": "United States",
"current_industry": "Information Technology",
"functional_area": [
"Sales"
],
"linkedin_url": "https://linkedin.com/in/morganhebb",
"business_email": "morgan.hebb@packback.co",
"business_email_risk_score": "A",
"business_email_validated_at": "2026-08-25",
"current_role_start_date": "2025-10-01",
"last_updated_at": "2026-08-01",
"company": {
"name": "Packback",
"size": "101",
"industry": "Information Technology",
"website_url": "https://www.packback.co/",
"domain": "packback.co",
"linkedin_url": "linkedin.com/company/packback",
"naics_codes": [
"5112",
"51121",
"511210"
],
"naics_titles": [
"Software Publishers"
],
"linkedin_industry": [
"E-Learning Providers"
],
"logo_url": "https://cdn.mixrank.com/md5/0c5b75379a35b0e1fc8a4b6e77fb2ba8"
},
"_id": "morganhebb",
"_score": 9.1714
}
],
"total": 278
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 89999,
"records_reset_5h": "2026-08-25T15:46:15Z",
"records_remaining_1w": 300423,
"records_reset_1w": "2026-08-30T08:00:07Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"results": [],
"total": 0
},
"status": "not_found",
"metadata": {
"fair_use": {
"records_remaining_5h": 89999,
"records_reset_5h": "2026-08-25T15:46:15Z",
"records_remaining_1w": 300423,
"records_reset_1w": "2026-08-30T08:00:07Z"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit, Fair Use window exhausted, or too many concurrent searches",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/search_companies": {
"post": {
"summary": "Search for Companies",
"operationId": "searchCompanyProfiles",
"description": "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.\n\nUse `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.\n\nEvery positive filter accepts either a single value or a list of values. A list is OR within its field and AND across fields, so `industry: [\"Information Technology\", \"Finance and Banking\"]` with `country: [\"United States\", \"Canada\"]` means (Information Technology or Finance and Banking) in (United States or Canada) — one search instead of one per value, with every match ranked together.\n\nThe `exclude_*` parameters (`exclude_domain`, `exclude_industry`, `exclude_employee_range`, `exclude_revenue_range`) work the other way round: each one also takes a list, but 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.\n\n**Use this endpoint to:**\n- Build prospect lists for account-based marketing\n- Qualify target accounts before outreach\n- Enrich CRM records with firmographic data\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Search.\n\n**Outcomes:**\nA 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.",
"tags": [
"Search"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Full-text search across company name only. Do not put domain, industry, employee size, or revenue here — use the dedicated filter params for those."
},
"domain": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact company domain filter. Full URLs are normalised automatically (\"https://www.acme.com/about\" → \"acme.com\"), so there is no need to strip the protocol or path yourself. Prefer this over `query` when you know the domain, since it is a precise match rather than a text search. Accepts a single value or a list — a list matches any of its values (OR), so `domain: [\"acme.com\", \"stripe.com\"]` returns records matching either.",
"example": "moltsets.com"
},
"industry": {
"oneOf": [
{
"type": "string",
"enum": [
"Professional and Business Services",
"Information Technology",
"Manufacturing",
"Retail",
"Health and Pharmaceuticals",
"Creative Arts and Entertainment",
"Construction",
"Marketing & Advertising",
"Finance and Banking",
"Tourism and Hospitality",
"Non-Profit and Social Services",
"Food and Beverage",
"Real Estate",
"Education",
"Transportation and Logistics",
"Media and Publishing",
"Energy",
"Government and Public Administration",
"Automotive",
"Telecommunications",
"Agriculture",
"Utilities"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Professional and Business Services",
"Information Technology",
"Manufacturing",
"Retail",
"Health and Pharmaceuticals",
"Creative Arts and Entertainment",
"Construction",
"Marketing & Advertising",
"Finance and Banking",
"Tourism and Hospitality",
"Non-Profit and Social Services",
"Food and Beverage",
"Real Estate",
"Education",
"Transportation and Logistics",
"Media and Publishing",
"Energy",
"Government and Public Administration",
"Automotive",
"Telecommunications",
"Agriculture",
"Utilities"
]
}
}
],
"description": "Exact industry filter. These 22 buckets are the only supported values, and must match exactly, including capitalisation and punctuation (note the ampersand in \"Marketing & Advertising\"). For a niche the buckets cannot express — insurance carriers, aerospace, mining — use `linkedin_industry` instead. Accepts a single value or a list — a list matches any of its values (OR), so `industry: [\"Information Technology\", \"Finance and Banking\"]` returns records matching either."
},
"employee_range": {
"oneOf": [
{
"type": "string",
"enum": [
"1-10",
"11-20",
"21-50",
"51-200",
"201-500",
"501-1000",
"1001-5000",
"5001+"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"1-10",
"11-20",
"21-50",
"51-200",
"201-500",
"501-1000",
"1001-5000",
"5001+"
]
}
}
],
"description": "Exact employee count range filter. These eight numeric bands are the only supported values — \"1-10\" holds the most records by a wide margin, \"5001+\" the fewest. Accepts a single value or a list — a list matches any of its values (OR), so `employee_range: [\"51-200\", \"201-500\"]` returns records matching either."
},
"revenue_range": {
"oneOf": [
{
"type": "string",
"enum": [
"Below $500k",
"$500k - $1M",
"$1M - $5M",
"$5M - $10M",
"$10M - $20M",
"$20M - $50M",
"Above $50M"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Below $500k",
"$500k - $1M",
"$1M - $5M",
"$5M - $10M",
"$10M - $20M",
"$20M - $50M",
"Above $50M"
]
}
}
],
"description": "Exact annual revenue range filter. These seven bands are the only supported values — \"$500k - $1M\" is the most common. \"Above $50M\" is a flat catch-all for all revenue over $50M; there is no finer band above it, so use it for any large-enterprise revenue target. Accepts a single value or a list — a list matches any of its values (OR), so `revenue_range: [\"$10M - $20M\", \"$20M - $50M\"]` returns records matching either."
},
"naics_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact NAICS industry code filter (~50% filled). Works at any level of the hierarchy, from the 2-digit sector (\"23\" = Construction, \"54\" = Professional Services) through to the 6-digit national industry (\"541120\" = Offices of Notaries, \"511210\" = Software Publishers). Use a short code for broad industry targeting and a longer code for precision — the most standardised industry filter available. Accepts a single value or a list — a list matches any of its values (OR), so `naics_code: [\"5112\", \"5415\"]` returns records matching either.",
"example": "541120"
},
"linkedin_industry": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact LinkedIn industry label filter (~85% filled). Uses LinkedIn's own industry vocabulary, which is far finer-grained than the 22 buckets in `industry`. Must match the stored label exactly, with standard capitalisation — for example \"Software Development\", \"Hospitality\", \"Legal Services\", \"Staffing and Recruiting\", \"Wellness and Fitness Services\". Accepts a single value or a list — a list matches any of its values (OR), so `linkedin_industry: [\"Software Development\", \"IT Services and IT Consulting\"]` returns records matching either.",
"example": "Software Development"
},
"country": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact country name filter on the company's location. Use the full English country name. Note that company 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 — combine it with other filters rather than relying on location alone when targeting global companies. Accepts a single value or a list — a list matches any of its values (OR), so `country: [\"United States\", \"Canada\"]` returns records matching either.",
"example": "United States"
},
"state": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Exact state or region name filter on the company's location. Accepts the full name with standard capitalisation or its abbreviation — \"Texas\" and \"TX\" both work. Canadian provinces match by their two-letter code too — \"Ontario\" or \"ON\", \"British Columbia\" or \"BC\", \"Quebec\" or \"QC\". Combine with `country` for precision. Location is team-derived in the same way as `country`, so it is most accurate for smaller companies. Accepts a single value or a list — a list matches any of its values (OR), so `state: [\"Texas\", \"Florida\"]` returns records matching either.",
"example": "Texas"
},
"exclude_domain": {
"type": "array",
"items": {
"type": "string"
},
"description": "Company domains to exclude. Any company on this list is dropped from the results — this is the suppression list, so pass the accounts you already have (existing customers, current vendors, your own company) and they never come back. Full URLs are normalised automatically, exactly as with `domain`. Excluded records cost you nothing: they consume no tokens and no fair use records, so excluding here is always cheaper than filtering the results yourself.",
"example": [
"acme.com",
"stripe.com"
]
},
"exclude_industry": {
"type": "array",
"items": {
"type": "string"
},
"description": "Industries to exclude. Companies in any listed industry are dropped. Accepts the same values as `industry`. Exclusion only removes companies that positively carry one of these values, so companies with no industry on record still appear in your results.",
"example": [
"Education",
"Non-Profit and Social Services"
]
},
"exclude_employee_range": {
"type": "array",
"items": {
"type": "string"
},
"description": "Employee count bands to exclude. Companies in any listed band are dropped. Accepts the same values as `employee_range` — for example [\"1-10\", \"11-20\"] to skip the very smallest companies, or [\"5001+\"] to skip enterprises.",
"example": [
"1-10",
"11-20"
]
},
"exclude_revenue_range": {
"type": "array",
"items": {
"type": "string"
},
"description": "Revenue bands to exclude. Companies in any listed band are dropped. Accepts the same values as `revenue_range` — for example [\"Below $500k\"] to skip the smallest companies, or [\"Above $50M\"] to skip large enterprises.",
"example": [
"Below $500k"
]
},
"limit": {
"type": "integer",
"description": "Number of results to return (default: 10, max: 25).",
"default": 10,
"minimum": 1,
"maximum": 25
},
"offset": {
"type": "integer",
"description": "Number of results to skip for pagination (default: 0). Use with limit to page through results — e.g. offset: 10 to get the second page of 10 results.",
"default": 0
}
}
},
"example": {
"industry": "Information Technology",
"employee_range": "51-200",
"revenue_range": "$10M - $20M",
"exclude_domain": [
"acme.com",
"stripe.com"
],
"limit": 10,
"offset": 0
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"results": [
{
"name": "Moltsets",
"domain": "moltsets.com",
"industry": "Information Technology",
"linkedin_url": "linkedin.com/company/moltsets-contact-data",
"revenue_range": "$1M - $5M",
"employee_count": "5",
"employee_range": "1-10",
"city": "San Carlos",
"state": "California",
"country": "United States",
"naics_codes": [
"5112",
"51121",
"511210"
],
"naics_titles": [
"Software Publishers"
],
"linkedin_industry": [
"Software Development"
],
"logo_url": "https://cdn.mixrank.com/md5/48188bb7d0df12849cabfeea895243ae",
"_id": "moltsets.com",
"_score": 18.4271
},
{
"name": "Acme Infolabs",
"domain": "acmeinfolabs.com",
"industry": "Information Technology",
"linkedin_url": "linkedin.com/company/acmeinfolabs",
"revenue_range": "$20M - $50M",
"employee_count": "57",
"employee_range": "51-200",
"city": "Bengaluru",
"state": "Karnataka",
"country": "India",
"naics_codes": [
"5415",
"54151",
"541511",
"541519"
],
"naics_titles": [
"Computer Systems Design and Related Services",
"Custom Computer Programming Services",
"Other Computer Related Services"
],
"linkedin_industry": [
"IT Services and IT Consulting"
],
"logo_url": "https://cdn.mixrank.com/md5/0e4e81c8ff584b1ce3e4c3067e8cb033",
"_id": "acmeinfolabs.com",
"_score": 15.0141
},
{
"name": "Acme Inc",
"domain": "atmexpressfinancial.com",
"industry": "Information Technology",
"linkedin_url": "linkedin.com/company/acme-inc",
"revenue_range": "Above $50M",
"employee_count": "150",
"employee_range": "51-200",
"city": "Denver",
"state": "Colorado",
"country": "United States",
"_id": "atmexpressfinancial.com",
"_score": 15.0141
}
],
"total": 210
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 89999,
"records_reset_5h": "2026-08-25T15:46:15Z",
"records_remaining_1w": 300423,
"records_reset_1w": "2026-08-30T08:00:07Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"results": [],
"total": 0
},
"status": "not_found",
"metadata": {
"fair_use": {
"records_remaining_5h": 89999,
"records_reset_5h": "2026-08-25T15:46:15Z",
"records_remaining_1w": 300423,
"records_reset_1w": "2026-08-30T08:00:07Z"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit, Fair Use window exhausted, or too many concurrent searches",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/search_linkedin_profile": {
"post": {
"summary": "Search for LinkedIn Profile",
"operationId": "linkedinSlugSearch",
"description": "The LinkedIn Profile Search API finds a person or company's LinkedIn profile from a name and company domain.\n\nPass 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.\n\nRun 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.\n\n**Use this endpoint to:**\n- Confirm you have the right LinkedIn profile before enriching a contact\n- Check match volume before running a bulk search\n- Attach LinkedIn URLs to contact records that are missing one\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Search.\n\n**Outcomes:**\nA 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.",
"tags": [
"Search"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Full name (e.g. 'John Smith') — parsed into first and last name automatically."
},
"first_name": {
"type": "string",
"description": "First name (used if `name` is not provided)."
},
"last_name": {
"type": "string",
"description": "Last name (used if `name` is not provided)."
},
"company": {
"type": "string",
"description": "Company domain (e.g. 'acme.com') or URL (e.g. 'https://acme.com') — normalized to domain.",
"example": "acme.com"
},
"company_domain": {
"type": "string",
"description": "Alias for `company` — company domain or URL."
},
"count_only": {
"type": "boolean",
"default": false,
"description": "Free — returns the count of matching results without fetching data or charging tokens. Use this first to gauge result volume before committing to a full search."
}
}
},
"example": {
"name": "John Smith",
"company": "acme.com",
"count_only": true
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"count_only": {
"summary": "Count only",
"value": {
"results": {
"count": 3
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"found": {
"summary": "Data found",
"value": {
"results": [
{
"full_name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"linkedin_slug": "john-smith-123",
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"company": "acme.com"
}
],
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": [],
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/search_business_email_by_name": {
"post": {
"summary": "Search Business Email by Name",
"operationId": "searchBusinessEmailByName",
"description": "The Business Email Finder API finds a person's valid work email address from just their name and company domain.\n\nIt 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.\n\n**Use this endpoint to:**\n- Find a prospect's work email before outreach\n- Fill in missing email fields on a lead list\n- Enrich CRM records with verified contact emails\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Search.\n\n**Outcomes:**\nA 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.",
"tags": [
"Search"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Full name (e.g. 'John Smith') — parsed into first and last name automatically."
},
"first_name": {
"type": "string",
"description": "First name (used if `name` is not provided)."
},
"last_name": {
"type": "string",
"description": "Last name (used if `name` is not provided)."
},
"company": {
"type": "string",
"description": "Company domain (e.g. 'acme.com') or URL (e.g. 'https://acme.com') — normalized to domain.",
"example": "acme.com"
},
"company_domain": {
"type": "string",
"description": "Alias for `company` — company domain or URL."
}
}
},
"example": {
"name": "John Smith",
"company": "acme.com"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"email": "john.smith@acme.com",
"risk_score": "A",
"linkedin_url": "https://linkedin.com/in/john-smith-123"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"email": null,
"risk_score": null,
"linkedin_url": 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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/search_business_profile_by_name": {
"post": {
"summary": "Search Business Profile by Name",
"operationId": "searchBusinessProfileByName",
"description": "The Business Profile Finder API finds anyone's full business profile from just their name and company domain.\n\nIt runs a LinkedIn profile search and a firmographic lookup in a single call, and returns the person's full business profile: name, job title, seniority, LinkedIn summary, skills, location, business email, hashed business emails, and personal emails, plus company firmographics such as industry, NAICS and SIC codes, headcount, and revenue. Pass `include_experience: true` to add the person's full job history. 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.\n\n**Use this endpoint to:**\n- Build a complete picture of a contact and their employer in one call\n- Qualify leads with company context before outreach\n- Enrich CRM records with job title and firmographic data\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Search.\n\n**Response fields:**\n- `summary` is the person's LinkedIn \"about\" text. `position_summary` describes their current role.\n- `skills` and `interests` are arrays of strings. `connection_count` is the person's LinkedIn connection count, capped at `500`. Like LinkedIn's own \"500+\", a value of `500` means 500 or more.\n- `business_email_md5s` holds the MD5 of every business email MoltSets holds for the person. `business_email_sha256s` holds the SHA256 of the same emails. Both can be present even when `business_email` is empty. `business_email` stays the single best validated pick.\n- `company` adds `description`, `linkedin_industry` (LinkedIn's own industry label, next to `industry`), `naics_codes` and `sic_codes` (arrays of `{code, title}`), and `revenue` (an exact figure, next to `revenue_range`).\n- `experience` is returned only when you pass `include_experience: true`. It is an array of roles, each with `title`, `company`, `company_linkedin_url`, `start_date`, `end_date`, `is_current`, `seniority`, `function`, and `description`. More than one role can be current. A current role has no `end_date`. Any field without data is left out of a role.\n- In a found profile, a field with no data can be left out of `results` (or `company`) rather than returned as `null` or `[]`. This applies to fields such as `skills`, `interests`, `current_role_start_date`, `sic_codes`, and `revenue`. Check for a field before reading it.\n\n**Personal email availability:**\nPersonal email fields (`personal_email`, `personal_emails`, and their `_validated_at` and `_risk_score` companions) are returned only when your plan includes personal email. Call `get_account` and read `personal_email_available`. On other plans these fields are withheld and `metadata.personal_email_restricted` is `true`.\n\n**Hashed email availability:**\n`business_email_md5s` is returned on all plans. `business_email_sha256s` is not available on the \\$397 / month and \\$997 / month plans. On those plans the field is stripped from `results` and `metadata.identity_hashes_restricted` is `true`. Read a missing `business_email_sha256s` as a plan boundary, not as absent data.\n\n**Outcomes:**\nA 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.",
"tags": [
"Search"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Full name (e.g. 'John Smith') — parsed into first and last name automatically."
},
"first_name": {
"type": "string",
"description": "First name (used if `name` is not provided)."
},
"last_name": {
"type": "string",
"description": "Last name (used if `name` is not provided)."
},
"company": {
"type": "string",
"description": "Company domain (e.g. 'acme.com') or URL (e.g. 'https://acme.com') — normalized to domain.",
"example": "acme.com"
},
"company_domain": {
"type": "string",
"description": "Alias for `company` — company domain or URL."
},
"include_experience": {
"type": "boolean",
"default": false,
"description": "Set to `true` to add `experience`, the person's full job history. Off by default because job history is the bulk of a profile. The current role is always returned in `title`, `seniority`, `functional_area`, and `current_role_start_date`."
}
}
},
"example": {
"name": "John Smith",
"company": "acme.com"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"business_email_sha256s": [
"f101da855ed67dc34c9729f04df8aeefXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"found_with_experience": {
"summary": "Data found, with include_experience: true",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"business_email_sha256s": [
"f101da855ed67dc34c9729f04df8aeefXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"experience": [
{
"title": "Senior Associate - Technical Director",
"company": "MoltSets",
"company_linkedin_url": "https://www.linkedin.com/company/moltsets",
"start_date": "2023-09-01",
"is_current": true,
"description": "Leads data infrastructure for GTM enrichment products.",
"seniority": "Senior",
"function": "Engineering"
},
{
"title": "Data Engineer",
"company": "Acme Inc",
"company_linkedin_url": "https://www.linkedin.com/company/acme",
"start_date": "2019-04-01",
"end_date": "2023-08-01",
"is_current": false,
"seniority": "Entry",
"function": "Engineering"
}
],
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"hashes_restricted": {
"summary": "Data found on the $397 or $997 plan (SHA256 hashes stripped)",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
},
"identity_hashes_restricted": true
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"linkedin_url": null,
"first_name": null,
"last_name": null,
"full_name": null,
"title": null,
"headline": null,
"summary": null,
"position_summary": null,
"seniority": null,
"functional_area": null,
"skills": [],
"interests": [],
"connection_count": null,
"city": null,
"state": null,
"country": null,
"business_email": null,
"business_email_validated_at": null,
"business_email_md5s": [],
"business_email_sha256s": [],
"personal_email": null,
"personal_email_validated_at": null,
"personal_emails": [],
"personal_emails_validated_at": [],
"current_role_start_date": null,
"company": {
"name": null,
"linkedin_url": null,
"website_url": null,
"description": null,
"industry": null,
"linkedin_industry": null,
"naics_codes": [],
"sic_codes": [],
"employee_count": null,
"employee_range": null,
"revenue": null,
"revenue_range": null
},
"last_updated_at": null,
"business_email_risk_score": null,
"personal_email_risk_score": null,
"personal_emails_risk_score": []
},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_best_email": {
"post": {
"summary": "LinkedIn to Best Email",
"operationId": "enrichEmail",
"description": "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`).\n\nIt 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.\n\n**Use this endpoint to:**\n- Enrich LinkedIn-sourced leads with a working email address\n- Maximise match rate across business and personal inboxes\n- Fill contact records that only have a LinkedIn URL\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Valid Emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"linkedin_url": {
"type": "string",
"description": "Single LinkedIn profile URL or slug."
},
"linkedin_urls": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of LinkedIn profile URLs or slugs, up to 100."
}
}
},
"examples": {
"single": {
"summary": "Single lookup",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"linkedin_urls": [
"https://linkedin.com/in/retentionadam",
"https://linkedin.com/in/jane-doe"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"email": {
"type": "string",
"nullable": true,
"description": "Email address found, or null if not found."
},
"risk_score": {
"type": "string",
"nullable": true,
"enum": [
"A",
"B",
"C",
"D",
"F",
null
],
"description": "Send-safety grade for the mailbox — deliverability, NOT whether the address belongs to the person looked up. A=validated deliverable; B=known engagement (a past open/click/order proves a send landed without bouncing); C=catch-all domain, deliverability unknowable; D=hard negative (spam trap/abuse/do-not-mail, or a complaint sighting in the last 6 months); F=no signal. Precedence when signals disagree: D > A > B > C > F. Absent when a scoring lookup is degraded — treat a missing grade as F."
},
"type": {
"type": "string",
"nullable": true,
"enum": [
"business",
"personal",
null
],
"description": "Whether the returned email is a business or personal address."
},
"last_validated_at": {
"type": "string",
"nullable": true,
"description": "ISO 8601 timestamp of last validation, or null."
}
}
},
"status": {
"type": "string",
"enum": [
"ok",
"not_found"
],
"description": "`ok` when the lookup found data, `not_found` when it completed but matched nothing. A miss is still HTTP 200 and costs no tokens."
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
}
},
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"email": "john.smith@example.com",
"risk_score": "A",
"type": "business",
"last_validated_at": "2026-03-04"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_business_email": {
"post": {
"summary": "LinkedIn to Business Email",
"operationId": "enrichBusinessEmail",
"description": "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`).\n\nIt 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.\n\n**Use this endpoint to:**\n- Reach prospects at their work email address\n- Enrich B2B lead lists with corporate emails\n- Power account-based marketing and sales sequences\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Valid Emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"linkedin_url": {
"type": "string",
"description": "Single LinkedIn profile URL or slug."
},
"linkedin_urls": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of LinkedIn profile URLs or slugs, up to 100."
}
}
},
"examples": {
"single": {
"summary": "Single lookup",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"linkedin_urls": [
"https://linkedin.com/in/retentionadam",
"https://linkedin.com/in/jane-doe"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Valid business email address",
"nullable": true
},
"risk_score": {
"type": "string",
"nullable": true,
"enum": [
"A",
"B",
"C",
"D",
"F",
null
],
"description": "Send-safety grade for the mailbox — deliverability, NOT whether the address belongs to the person looked up. A=validated deliverable; B=known engagement (a past open/click/order proves a send landed without bouncing); C=catch-all domain, deliverability unknowable; D=hard negative (spam trap/abuse/do-not-mail, or a complaint sighting in the last 6 months); F=no signal. Precedence when signals disagree: D > A > B > C > F. Absent when a scoring lookup is degraded — treat a missing grade as F."
}
}
},
"status": {
"type": "string",
"enum": [
"ok",
"not_found"
],
"description": "`ok` when the lookup found data, `not_found` when it completed but matched nothing. A miss is still HTTP 200 and costs no tokens."
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
}
},
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"email": "john.smith@example.com",
"risk_score": "A"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"email": null,
"risk_score": 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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_personal_email_usa": {
"post": {
"summary": "LinkedIn to Personal Email (US-only)",
"operationId": "enrichPersonalEmail",
"description": "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`). This endpoint is US-only data.\n\nUse 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.\n\n**Use this endpoint to:**\n- Reach candidates or prospects outside working hours\n- Improve deliverability for consumer marketing sends\n- Re-engage contacts who've left their previous employer\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Plan Availability:**\nThis endpoint is not available on every plan. Access is set 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.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Valid Emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"linkedin_url": {
"type": "string",
"description": "Single LinkedIn profile URL or slug."
},
"linkedin_urls": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of LinkedIn profile URLs or slugs, up to 100."
}
}
},
"examples": {
"single": {
"summary": "Single lookup",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"linkedin_urls": [
"https://linkedin.com/in/retentionadam",
"https://linkedin.com/in/jane-doe"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"email": "john.smith@gmail.com",
"risk_score": "A",
"last_validated_at": "2026-03-04"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"email": null,
"risk_score": 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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_best_personal_email_usa": {
"post": {
"summary": "LinkedIn to Best Personal Email (US-only)",
"operationId": "linkedinToBestPersonalEmail",
"description": "The LinkedIn to Best Personal Email API turns a LinkedIn profile into a valid personal email address in a single call. This endpoint is US-only data. It supports single lookups (`linkedin_url`) and batch lookups of up to 100 profiles at once (`linkedin_urls`).\n\nPass 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.\n\n**Use this endpoint to:**\n- Get the single best personal email for a contact, with confidence\n- Confirm an email is still active before sending\n- Enrich records where deliverability matters most\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Plan Availability:**\nThis endpoint is not available on every plan. Access is set 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.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Valid Emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"linkedin_url": {
"type": "string",
"description": "Single LinkedIn profile URL or slug."
},
"linkedin_urls": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of LinkedIn profile URLs or slugs, up to 100."
}
}
},
"examples": {
"single": {
"summary": "Single lookup",
"value": {
"linkedin_url": "https://linkedin.com/in/johndoe"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"linkedin_urls": [
"https://linkedin.com/in/johndoe",
"https://linkedin.com/in/jane-doe"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"email": "john.smith@gmail.com",
"risk_score": "A",
"last_validated_at": "2026-03-04"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"email": null,
"risk_score": 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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_mobile_phone": {
"post": {
"summary": "LinkedIn to Mobile Phone",
"operationId": "enrichPhone",
"description": "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.\n\nOnly 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** at 1 phone token per returned result. Phone tokens are separate from your regular token balance and aren't included in any plan: they come from a monthly phone token subscription, available on paid plans only. Unused phone tokens roll over while the subscription is active.\n\n**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.\n\n**Use this endpoint to:**\n- Power SMS outreach and cold calling\n- Enrich sales sequences with direct-dial mobile numbers\n- Batch-append verified phone numbers to a contact list\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Carrier-Verified Mobile Phones"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"linkedin_url": {
"type": "string",
"description": "Single LinkedIn profile URL."
},
"linkedin_urls": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of LinkedIn profile URLs, up to 100."
}
}
},
"examples": {
"single": {
"summary": "Single lookup",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"linkedin_urls": [
"https://linkedin.com/in/retentionadam",
"https://linkedin.com/in/jane-doe"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"mobile_phone": "5555555555",
"last_validated_at": "2026-03-04"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
},
"phone_tokens_used": 1,
"phone_tokens_remaining": 498
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"mobile_phone": 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"
},
"phone_tokens_used": 0,
"phone_tokens_remaining": 498
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — out of tokens or phone tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/reverse_email_lookup": {
"post": {
"summary": "Reverse Email Lookup",
"operationId": "hemToBusinessProfile",
"description": "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.\n\nIt supports single lookups (`email`) and batch lookups of up to 100 addresses at once (`emails`). Each address in a batch counts as one request against your Fair Use requests limit.\n\n**Use this endpoint to:**\n- Enrich inbound leads and form fills with full contact context\n- Qualify a prospect before you reach out\n- Fill in missing profile data on an existing email list\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Reverse Lookups"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Single email address."
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Batch of email addresses, up to 100. Can't be combined with `email`."
}
}
},
"examples": {
"email": {
"summary": "Single lookup",
"value": {
"email": "john.smith@example.com"
}
},
"batch": {
"summary": "Batch lookup",
"value": {
"emails": [
"john.smith@example.com",
"jane.doe@example.com"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"first_name": "John",
"last_name": "Smith",
"title": "Principal Cybersecurity Engineer",
"seniority": "Manager",
"functional_area": "Information Technology",
"linkedinurl": "https://www.linkedin.com/in/john-smith-123",
"current_company": "MoltSets",
"current_company_url": "https://moltsets.com",
"current_company_linkedinurl": "https://linkedin.com/company/moltsets",
"country": "United States",
"company_employee_count": "3",
"company_employee_range": "1-10",
"company_revenue": "1200000",
"company_revenue_range": "$1M - $5M",
"work_email_confirmed": "a4cd87c390c98385297fbe9250XXXXX",
"work_email_confirmed_status": "2025-10-12",
"work_email_confirmed_risk_score": "A",
"personal_emails": [
"3018fe3a783fad1db0370ee3fXXXXX"
],
"personal_emails_status": [
null
],
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"first_name": null,
"last_name": null,
"title": null,
"seniority": null,
"functional_area": null,
"linkedinurl": null,
"current_company": null,
"current_company_url": null,
"current_company_linkedinurl": null,
"country": null,
"company_employee_count": null,
"company_employee_range": null,
"company_revenue": null,
"company_revenue_range": null,
"work_email_confirmed": null,
"work_email_confirmed_status": null,
"work_email_confirmed_risk_score": null,
"personal_emails": [],
"personal_emails_status": [],
"personal_emails_risk_score": []
},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/reverse_linkedin_lookup": {
"post": {
"summary": "Reverse LinkedIn Lookup",
"operationId": "linkedinToBusinessProfile",
"description": "The Reverse LinkedIn Lookup API resolves a LinkedIn profile URL into a complete business profile, including full name, job title, seniority, LinkedIn summary, skills, location, a valid business email, hashed business emails, and a personal email, plus company firmographics such as industry, NAICS and SIC codes, headcount, and revenue. Pass `include_experience: true` to add the person's full job history.\n\nThis 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.\n\n**Use this endpoint to:**\n- Turn a LinkedIn URL into a fully enriched contact record\n- Get company firmographics alongside personal contact details\n- Power CRM enrichment workflows from a single input\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Response fields:**\n- `summary` is the person's LinkedIn \"about\" text. `position_summary` describes their current role.\n- `skills` and `interests` are arrays of strings. `connection_count` is the person's LinkedIn connection count, capped at `500`. Like LinkedIn's own \"500+\", a value of `500` means 500 or more.\n- `business_email_md5s` holds the MD5 of every business email MoltSets holds for the person. `business_email_sha256s` holds the SHA256 of the same emails. Both can be present even when `business_email` is empty. `business_email` stays the single best validated pick.\n- `company` adds `description`, `linkedin_industry` (LinkedIn's own industry label, next to `industry`), `naics_codes` and `sic_codes` (arrays of `{code, title}`), and `revenue` (an exact figure, next to `revenue_range`).\n- `experience` is returned only when you pass `include_experience: true`. It is an array of roles, each with `title`, `company`, `company_linkedin_url`, `start_date`, `end_date`, `is_current`, `seniority`, `function`, and `description`. More than one role can be current. A current role has no `end_date`. Any field without data is left out of a role.\n- In a found profile, a field with no data can be left out of `results` (or `company`) rather than returned as `null` or `[]`. This applies to fields such as `skills`, `interests`, `current_role_start_date`, `sic_codes`, and `revenue`. Check for a field before reading it.\n\n**Personal email availability:**\nPersonal email fields (`personal_email`, `personal_emails`, and their `_validated_at` and `_risk_score` companions) are returned only when your plan includes personal email. Call `get_account` and read `personal_email_available`. On other plans these fields are withheld and `metadata.personal_email_restricted` is `true`.\n\n**Hashed email availability:**\n`business_email_md5s` is returned on all plans. `business_email_sha256s` is not available on the \\$397 / month and \\$997 / month plans. On those plans the field is stripped from `results` and `metadata.identity_hashes_restricted` is `true`. Read a missing `business_email_sha256s` as a plan boundary, not as absent data.\n\n**Outcomes:**\nA 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.",
"tags": [
"Reverse Lookups"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"linkedin_url"
],
"properties": {
"linkedin_url": {
"type": "string",
"example": "https://linkedin.com/in/retentionadam"
},
"include_experience": {
"type": "boolean",
"default": false,
"description": "Set to `true` to add `experience`, the person's full job history. Off by default because job history is the bulk of a profile. The current role is always returned in `title`, `seniority`, `functional_area`, and `current_role_start_date`."
}
}
},
"examples": {
"default": {
"summary": "Profile without job history",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam"
}
},
"with_experience": {
"summary": "Profile with full job history",
"value": {
"linkedin_url": "https://linkedin.com/in/retentionadam",
"include_experience": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"business_email_sha256s": [
"f101da855ed67dc34c9729f04df8aeefXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"found_with_experience": {
"summary": "Data found, with include_experience: true",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"business_email_sha256s": [
"f101da855ed67dc34c9729f04df8aeefXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"experience": [
{
"title": "Senior Associate - Technical Director",
"company": "MoltSets",
"company_linkedin_url": "https://www.linkedin.com/company/moltsets",
"start_date": "2023-09-01",
"is_current": true,
"description": "Leads data infrastructure for GTM enrichment products.",
"seniority": "Senior",
"function": "Engineering"
},
{
"title": "Data Engineer",
"company": "Acme Inc",
"company_linkedin_url": "https://www.linkedin.com/company/acme",
"start_date": "2019-04-01",
"end_date": "2023-08-01",
"is_current": false,
"seniority": "Entry",
"function": "Engineering"
}
],
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"hashes_restricted": {
"summary": "Data found on the $397 or $997 plan (SHA256 hashes stripped)",
"value": {
"results": {
"linkedin_url": "https://linkedin.com/in/john-smith-123",
"first_name": "John",
"last_name": "Smith",
"full_name": "John Smith",
"title": "Senior Associate - Technical Director",
"headline": "Technical Director @ MoltSets | Data infrastructure for GTM teams",
"summary": "Technical director building data infrastructure for go-to-market teams.",
"position_summary": "Leads the data platform behind MoltSets enrichment APIs.",
"seniority": "Senior",
"functional_area": "Engineering",
"skills": [
"Data Engineering",
"Python",
"PostgreSQL"
],
"interests": [
"B2B SaaS",
"Open Source"
],
"connection_count": 500,
"city": "Denver",
"state": "Colorado",
"country": "United States",
"business_email": "john.smith@example.com",
"business_email_validated_at": "2026-09-12",
"business_email_md5s": [
"900b89c0e5ece81f7fb0a72ef3dXXXXX"
],
"personal_email": "john.smith@gmail.com",
"personal_email_validated_at": "2026-09-29",
"personal_emails": [
"jsmith.denver@gmail.com"
],
"personal_emails_validated_at": [
"2026-08-06"
],
"current_role_start_date": "2023-09-01",
"company": {
"name": "MoltSets",
"linkedin_url": "linkedin.com/company/moltsets",
"website_url": "moltsets.com",
"description": "MoltSets is a go-to-market enrichment API for AI agents.",
"industry": "Information Technology",
"linkedin_industry": "Software Development",
"naics_codes": [
{
"code": "518210",
"title": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services"
}
],
"sic_codes": [
{
"code": "7374",
"title": "Computer Processing and Data Preparation"
}
],
"employee_count": 9,
"employee_range": "1-10",
"revenue": 3200000,
"revenue_range": "$1M - $5M"
},
"last_updated_at": "2025-04-01",
"business_email_risk_score": "A",
"personal_email_risk_score": "A",
"personal_emails_risk_score": [
"A"
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
},
"identity_hashes_restricted": true
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"linkedin_url": null,
"first_name": null,
"last_name": null,
"full_name": null,
"title": null,
"headline": null,
"summary": null,
"position_summary": null,
"seniority": null,
"functional_area": null,
"skills": [],
"interests": [],
"connection_count": null,
"city": null,
"state": null,
"country": null,
"business_email": null,
"business_email_validated_at": null,
"business_email_md5s": [],
"business_email_sha256s": [],
"personal_email": null,
"personal_email_validated_at": null,
"personal_emails": [],
"personal_emails_validated_at": [],
"current_role_start_date": null,
"company": {
"name": null,
"linkedin_url": null,
"website_url": null,
"description": null,
"industry": null,
"linkedin_industry": null,
"naics_codes": [],
"sic_codes": [],
"employee_count": null,
"employee_range": null,
"revenue": null,
"revenue_range": null
},
"last_updated_at": null,
"business_email_risk_score": null,
"personal_email_risk_score": null,
"personal_emails_risk_score": []
},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/email_to_maid": {
"post": {
"summary": "Email to MAID",
"operationId": "hemToMaid",
"description": "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).\n\nMAIDs 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.\n\n**Use this endpoint to:**\n- Build mobile retargeting audiences from your contact list\n- Activate programmatic ad campaigns against known contacts\n- Connect email identities to mobile device signals for cross-device targeting\n\n**Need multiple MAIDs?**\nThis API returns only ONE MAID. If you are running ads and want MULTIPLE MAIDs, and are willing to spend at least $10k/yr, please click here and talk to our data team.\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Plan Availability:**\nThis endpoint is not available on the \\$397 / month and \\$997 / month plans. Calls from those plans return `403` with `plan_restricted`. It is a plan condition, so retrying or topping up tokens does not clear it.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Ad Audience"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address."
}
}
},
"examples": {
"email": {
"summary": "Using email",
"value": {
"email": "john.smith@example.com"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": [
{
"device_id": "b8c747bb-96c5-453f-b770-9d64889XXXXX",
"device_type": "AAID"
}
],
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": [],
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/business_email_to_sha256": {
"post": {
"summary": "Business Email to SHA256",
"operationId": "businessEmailToSHA256",
"description": "The Business Email to SHA256 API converts a business email address into a SHA256-hashed personal email address, for privacy-safe identity resolution and paid advertising audience matching.\n\nThe hash 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.\n\n**Use this endpoint to:**\n- Build customer match audiences for Meta, Google, LinkedIn, or TikTok\n- Retarget contacts on their personal devices without exposing raw email addresses\n- Bridge business contacts to privacy-safe advertising identifiers\n\n**Need multiple SHA256s?**\nThis API returns only ONE SHA256. If you are running ads and want MULTIPLE SHA256's, and are willing to spend at least $10k/yr, please click here and talk to our data team.\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Plan Availability:**\nThis endpoint is not available on the \\$397 / month and \\$997 / month plans. Calls from those plans return `403` with `plan_restricted`. It is a plan condition, so retrying or topping up tokens does not clear it.\n\n**Response fields:**\n`personal_email_SHA256` holds one string, not an array. When there's no data, the field is left out of `results`.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Ad Audience"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Business email address."
}
}
},
"examples": {
"email": {
"summary": "Using email",
"value": {
"email": "john.smith@example.com"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"personal_email_SHA256": "e187e84b06e1e6577bcebe42d3905434ddc89d2d5abaab8e85691882310XXXXX"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/linkedin_to_sha256": {
"post": {
"summary": "LinkedIn to SHA256",
"operationId": "linkedinToSHA256",
"description": "The LinkedIn to SHA256 API retrieves a SHA256 and MD5 hashed email for a LinkedIn profile, covering both a business and a personal address.\n\nIt returns a single business hash and a single personal hash in each format, giving you broad coverage for audience matching across ad platforms. Use this when you need a full match key set for a LinkedIn-identified contact, for example to maximise match rates when uploading customer lists to Meta, Google, or LinkedIn Ads.\n\n**Use this endpoint to:**\n- Maximise match rates on ad platform customer lists\n- Build a complete hashed identity set for one contact\n- Bridge LinkedIn-sourced contacts into advertising audiences\n\n**Need multiple SHA256s?**\nThis API returns only ONE SHA256. If you are running ads and want MULTIPLE SHA256's, and are willing to spend at least $10k/yr, please click here and talk to our data team.\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Plan Availability:**\nThis endpoint is not available on the \\$397 / month and \\$997 / month plans. Calls from those plans return `403` with `plan_restricted`. It is a plan condition, so retrying or topping up tokens does not clear it.\n\n**Response fields:**\nEach hash field holds one string, not an array. A field with no data is left out of `results`, so a profile with only a business email returns just the `business_` fields. Check for a field before reading it.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Ad Audience"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"linkedin_url"
],
"properties": {
"linkedin_url": {
"type": "string",
"example": "https://linkedin.com/in/retentionadam"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"linkedin_slug": "john-smith-123",
"business_SHA256_array": "f101da855ed67dc34c9729f04df8aeefXXXXX",
"business_md5_array": "900b89c0e5ece81f7fb0a72ef3dXXXXX",
"personal_SHA256_array": "266f422db074460bb5bf41984c3aXXXXX",
"personal_md5_array": "0c86fde3392c84d6514de378dc1XXXXX"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/email_to_linkedin": {
"post": {
"summary": "Email to LinkedIn",
"operationId": "hemToBestLinkedin",
"description": "The Email to LinkedIn API resolves an email address to the highest-confidence LinkedIn profile URL when multiple candidates exist.\n\nIt 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.\n\n**Use this endpoint to:**\n- Attach the correct LinkedIn profile to an email-only contact\n- Personalise outreach with accurate LinkedIn context\n- Trigger downstream enrichment workflows from an email address\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get LinkedIn"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address."
}
}
},
"examples": {
"email": {
"summary": "Using email",
"value": {
"email": "john.smith@example.com"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"linkedin_url": "https://www.linkedin.com/in/john-smith-123"
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"linkedin_url": 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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/ip_to_company": {
"post": {
"summary": "IP to Company",
"operationId": "ipToCompany",
"description": "The IP to Company API identifies the company associated with an IPv4 address.\n\nPass 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.\n\n**Use this endpoint to:**\n- De-anonymise B2B website traffic\n- Trigger account-based marketing and sales workflows\n- Feed a website visitor identification pipeline\n\n**Need premium IP to Company data?**\nIf you are looking for flat files with premium IP to Company resolution and are willing to spend at least $10k/yr, please click here to talk to our data team.\n\n**Fair Use Policy:**\nThis API is subject to our Fair Use Policy for Enrichment.\n\n**Outcomes:**\nA 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.",
"tags": [
"Get Company"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ip_address"
],
"properties": {
"ip_address": {
"type": "string",
"description": "IPv4 address to resolve.",
"example": "8.8.8.8"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"examples": {
"found": {
"summary": "Data found",
"value": {
"results": {
"companies": [
{
"domain": "acme.com",
"percentage": "1.0"
}
]
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
},
"not_found": {
"summary": "No data found — still HTTP 200",
"value": {
"results": {
"companies": []
},
"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"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"402": {
"description": "Payment Required — insufficient tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInsufficientTokens"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header, tool not on the plan, or account inactive",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorPlanRestricted"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — rate limit or Fair Use window exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/get_account": {
"post": {
"summary": "Get Account",
"operationId": "getAccount",
"description": "The Get Account API retrieves your MoltSets account details: account name, current plan, account status, remaining credit balance, whether personal-email lookups are on your plan (`personal_email_available`), live Fair Use standing (`fair_use`), phone token balance and phone token subscription, number of API keys, and user count.\n\n**Use this endpoint to:**\n- Check account health programmatically\n- Verify your account is active\n- Check whether `linkedin_to_personal_email_usa` and `linkedin_to_best_personal_email_usa` are available on your plan\n- Check your phone token balance before running `linkedin_to_mobile_phone`\n- Display account information inside your own application or dashboard",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "No arguments required. Send an empty object."
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Account ID"
},
"name": {
"type": "string",
"description": "Account name"
},
"status": {
"type": "string",
"description": "Account status",
"enum": [
"active",
"suspended"
]
},
"plan": {
"type": "string",
"description": "Current plan identifier"
},
"token_balance": {
"type": "integer",
"description": "Remaining token balance. `-1` when the account is unlimited."
},
"unlimited": {
"type": "boolean",
"description": "true if the account has unlimited tokens"
},
"fair_use": {
"type": "object",
"description": "Fair Use Policy limits, split by enrichment and search. Each has record and request limits over rolling windows.",
"properties": {
"enrich": {
"type": "object",
"properties": {
"records": {
"type": "object",
"description": "Record (result) limits.",
"properties": {
"5h": {
"type": "object",
"description": "Rolling 5-hour record limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
},
"1w": {
"type": "object",
"description": "Rolling 1-week record limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
}
}
},
"requests": {
"type": "object",
"description": "Request limits.",
"properties": {
"5h": {
"type": "object",
"description": "Rolling 5-hour request limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
}
}
}
}
},
"search": {
"type": "object",
"properties": {
"records": {
"type": "object",
"description": "Record (result) limits.",
"properties": {
"5h": {
"type": "object",
"description": "Rolling 5-hour record limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
},
"1w": {
"type": "object",
"description": "Rolling 1-week record limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
}
}
},
"requests": {
"type": "object",
"description": "Request limits.",
"properties": {
"5h": {
"type": "object",
"description": "Rolling 5-hour request limit.",
"properties": {
"limit": {
"type": "integer",
"description": "Cap for this window."
},
"used": {
"type": "integer",
"description": "Amount used in this window."
},
"remaining": {
"type": "integer",
"description": "Amount remaining in this window."
},
"resets_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when this window resets, or null if not yet started."
}
}
}
}
}
}
}
}
},
"search_trial": {
"type": "object",
"nullable": true,
"description": "Free-tier search trial standing. `null` on paid plans."
},
"phone_token_balance": {
"type": "integer",
"description": "Phone tokens available to spend on `linkedin_to_mobile_phone` results. Equal to `phone_tokens_plan` plus `phone_tokens_purchased`. `0` without a phone token subscription."
},
"phone_token_allowance": {
"type": "integer",
"description": "Phone tokens granted each month by your phone token subscription. `0` without a subscription."
},
"phone_tokens_purchased": {
"type": "integer",
"description": "Portion of `phone_token_balance` that came from purchased tokens."
},
"phone_tokens_plan": {
"type": "integer",
"description": "Portion of `phone_token_balance` that came from your phone token subscription, including tokens rolled over from earlier months."
},
"phone_plan": {
"type": "string",
"nullable": true,
"description": "Phone token subscription identifier, for example `phone_plan_27`. `null` without a subscription."
},
"phone_plan_ends_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "ISO 8601 timestamp when a cancelled phone token subscription ends. `null` while the subscription is active, or without one."
},
"personal_email_available": {
"type": "boolean",
"description": "`true` if the account's plan includes the dedicated personal-email tools (`linkedin_to_personal_email_usa`, `linkedin_to_best_personal_email_usa`). Where `false`, those tools return `403` with `plan_restricted`."
},
"api_key_count": {
"type": "integer",
"description": "Number of API keys on the account"
},
"user_count": {
"type": "integer",
"description": "Number of users on the account"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 account creation timestamp"
}
}
},
"status": {
"type": "string",
"example": "ok"
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
}
},
"examples": {
"with_phone_plan": {
"summary": "With a phone token subscription",
"value": {
"results": {
"id": "kZ9pQ2rt",
"name": "BrightHollow",
"status": "active",
"plan": "subscription_397",
"token_balance": -1,
"unlimited": true,
"fair_use": {
"enrich": {
"records": {
"5h": {
"limit": 150000,
"used": 20,
"remaining": 149980,
"resets_at": "2026-10-07T15:34:16Z"
},
"1w": {
"limit": 750000,
"used": 197,
"remaining": 749803,
"resets_at": "2026-10-11T18:54:25Z"
}
},
"requests": {
"5h": {
"limit": 750000,
"used": 21,
"remaining": 749979,
"resets_at": "2026-10-07T15:34:16Z"
}
}
},
"search": {
"records": {
"5h": {
"limit": 75000,
"used": 0,
"remaining": 75000,
"resets_at": null
},
"1w": {
"limit": 375000,
"used": 67649,
"remaining": 307351,
"resets_at": "2026-10-11T08:00:15Z"
}
},
"requests": {
"5h": {
"limit": 375000,
"used": 0,
"remaining": 375000,
"resets_at": null
}
}
}
},
"search_trial": null,
"phone_token_balance": 98,
"phone_token_allowance": 180,
"phone_tokens_purchased": 10,
"phone_tokens_plan": 88,
"phone_plan": "phone_plan_27",
"phone_plan_ends_at": null,
"personal_email_available": true,
"api_key_count": 3,
"user_count": 5,
"created_at": "2026-05-13T18:36:29Z"
},
"status": "ok",
"metadata": {}
}
},
"without_phone_plan": {
"summary": "Without a phone token subscription",
"value": {
"results": {
"id": "Xc4mT8wa",
"name": "Northwind Labs",
"status": "active",
"plan": "subscription_27",
"token_balance": -1,
"unlimited": true,
"fair_use": {
"enrich": {
"records": {
"5h": {
"limit": 1000,
"used": 0,
"remaining": 1000,
"resets_at": null
},
"1w": {
"limit": 5000,
"used": 2,
"remaining": 4998,
"resets_at": "2026-10-13T09:19:03Z"
}
},
"requests": {
"5h": {
"limit": 5000,
"used": 0,
"remaining": 5000,
"resets_at": null
}
}
},
"search": {
"records": {
"5h": {
"limit": 500,
"used": 0,
"remaining": 500,
"resets_at": null
},
"1w": {
"limit": 2500,
"used": 4,
"remaining": 2496,
"resets_at": "2026-10-13T07:56:06Z"
}
},
"requests": {
"5h": {
"limit": 2500,
"used": 0,
"remaining": 2500,
"resets_at": null
}
}
}
},
"search_trial": null,
"phone_token_balance": 0,
"phone_token_allowance": 0,
"phone_tokens_purchased": 0,
"phone_tokens_plan": 0,
"phone_plan": null,
"phone_plan_ends_at": null,
"personal_email_available": true,
"api_key_count": 1,
"user_count": 2,
"created_at": "2026-10-05T11:32:39Z"
},
"status": "ok",
"metadata": {}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorForbidden"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — burst guard (`rate_limited`). Account tools don't count toward the enrichment or search Fair Use limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/get_billing": {
"post": {
"summary": "Get Billing",
"operationId": "getBilling",
"description": "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.\n\n**Use this endpoint to:**\n- Monitor spend against your plan\n- Confirm your next renewal date\n- Display live billing information inside your own application",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "No arguments required. Send an empty object."
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "Current plan identifier"
},
"subscription_status": {
"type": "string",
"enum": [
"active",
"none",
"cancelled",
"past_due"
],
"description": "Subscription status"
},
"token_balance": {
"type": "integer",
"description": "Remaining token balance. `-1` when the account is unlimited."
},
"unlimited": {
"type": "boolean",
"description": "true if the account has unlimited tokens"
},
"current_period_start": {
"type": [
"string",
"null"
],
"format": "date",
"description": "ISO 8601 start of the current billing period, or null."
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date",
"description": "ISO 8601 end of the current billing period, or null."
},
"token_costs": {
"type": "object",
"description": "Token cost per tool call. Keys are tool names, values are integer token costs.",
"additionalProperties": {
"type": "integer"
}
}
}
},
"status": {
"type": "string",
"example": "ok"
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
}
},
"example": {
"results": {
"plan": "subscription_997",
"subscription_status": "active",
"token_balance": -1,
"unlimited": true,
"current_period_start": "2026-07-09",
"current_period_end": "2026-08-09",
"token_costs": {
"get_account": 0,
"get_billing": 0,
"get_usage": 0,
"business_email_to_sha256": 1,
"email_to_linkedin": 1,
"email_to_maid": 1,
"reverse_email_lookup": 1,
"ip_to_company": 1,
"linkedin_to_best_email": 1,
"linkedin_to_best_personal_email_usa": 1,
"linkedin_to_business_email": 1,
"linkedin_to_mobile_phone": 1,
"linkedin_to_personal_email_usa": 1,
"linkedin_to_sha256": 1,
"reverse_linkedin_lookup": 1,
"search_business_email_by_name": 1,
"search_business_profile_by_name": 1,
"search_companies": 1,
"search_linkedin_profile": 1,
"search_people": 1
}
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorForbidden"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — burst guard (`rate_limited`). Account tools don't count toward the enrichment or search Fair Use limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
},
"/get_usage": {
"post": {
"summary": "Get Usage",
"operationId": "getUsage",
"description": "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.\n\nIt returns a day-by-day log of API calls made, credits consumed, successful lookups, empty results, and failed requests, along with period totals.\n\n**Use this endpoint to:**\n- Track consumption trends over time\n- Audit usage day by day\n- Build internal usage dashboards",
"tags": [
"Account"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"period": {
"type": "string",
"enum": [
"today",
"week",
"month",
"billing_cycle"
],
"default": "today",
"description": "Time window to report on. Defaults to `today`."
}
}
},
"example": {
"period": "month"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"example": {
"results": {
"period": "today",
"start_date": "2026-07-14",
"end_date": "2026-07-14",
"token_balance": -1,
"days": [
{
"date": "2026-07-14",
"calls": 2634,
"tokens": 1405,
"with_data": 1422,
"without_data": 1195,
"failed": 17
}
],
"totals": {
"calls": 2634,
"tokens": 1405,
"with_data": 1422,
"without_data": 1195,
"failed": 17
}
},
"status": "ok",
"metadata": {
"fair_use": {
"records_remaining_5h": 179999,
"records_reset_5h": "2026-07-15T18:53:16Z",
"records_remaining_1w": 899999,
"records_reset_1w": "2026-07-22T13:53:16Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorUnauthorized"
}
}
}
},
"403": {
"description": "Forbidden — missing `User-Agent` header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorForbidden"
}
}
}
},
"422": {
"description": "Invalid Input — malformed body, or a parameter is missing, malformed, or outside its allowed values",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidInput"
}
}
}
},
"429": {
"description": "Too Many Requests — burst guard (`rate_limited`). Account tools don't count toward the enrichment or search Fair Use limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorRateLimit"
}
}
}
},
"500": {
"description": "Internal Server Error — the call could not complete. Usually the endpoint is temporarily unavailable, but an oversized request can also cause it. Retry with a smaller request first; the MoltSets team is alerted automatically.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInternal"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/UserAgentHeader"
}
]
}
}
},
"tags": [
{
"name": "Search",
"description": "Search and filter company and business profiles by name, domain, industry, size, or revenue."
},
{
"name": "Get Valid Emails",
"description": "Resolve and enrich valid business and personal email addresses."
},
{
"name": "Get Carrier-Verified Mobile Phones",
"description": "Enrich carrier-verified mobile phone numbers."
},
{
"name": "Reverse Lookups",
"description": "Resolve an email address or LinkedIn URL to a full business profile."
},
{
"name": "Get Ad Audience",
"description": "Resolve identifiers to hashed email (HEM) and mobile advertising IDs (MAIDs) for audience matching."
},
{
"name": "Get LinkedIn",
"description": "Resolve an email address to its LinkedIn profile URL."
},
{
"name": "Get Company",
"description": "Resolve IP addresses to company data."
},
{
"name": "Account",
"description": "Account management tools. Free — do not consume credits."
}
]
}