Overview

MoltSets is an identity resolution API. You give it a piece of data — an email address, LinkedIn URL, IP address, or a person’s name and company — and it returns enriched contact and company information, including hashed emails (HEMs) for ad audiences. Every tool follows the same request and response structure, so once you’ve made one call, you know how to make all of them.

Base URL

All API requests go to:

https://api.moltsets.com/api/v1/tools/

Each tool has its own endpoint path. For example:

POST https://api.moltsets.com/api/v1/tools/linkedin_to_best_email
POST https://api.moltsets.com/api/v1/tools/ip_to_company
POST https://api.moltsets.com/api/v1/tools/get_account

How a request works

Every request is a POST with a JSON body, an Authorization header, a Content-Type header, and a User-Agent header:

curl -X POST https://api.moltsets.com/api/v1/tools/linkedin_to_best_email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: YOUR_APP_NAME/1.0" \
  -d '{"linkedin_url": "https://linkedin.com/in/retentionadam"}'

User-Agent can be any non-empty value — MoltSets doesn’t validate its contents, only that it’s present. Requests without one are rejected with a 403 (forbidden). See Errors.

How a response works

Every call that completes returns HTTP 200 with a consistent envelope:

{
  "results": { ... },
  "status": "ok",
  "metadata": {
    "tokens_used": 1,
    "tokens_remaining": 206
  }
}

results — the data returned by the tool. Empty, or with its fields set to null, when no data is found.
status — "ok" when the tool found data, "not_found" when it completed but matched nothing.
metadata.fair_use — your remaining record headroom in the 5-hour and 1-week windows, and when each resets.
metadata.tokens_used — credits consumed. Always 0 when no data is returned. Sent on token-bound (free) accounts only — accounts on an unlimited plan omit it.
metadata.tokens_remaining — your remaining credit balance after this request. Token-bound accounts only.
metadata.personal_email_restricted — present and true only when the call withheld personal-email data because your plan doesn’t include that surface. Read the missing field as a plan boundary, not as absent data.
metadata.phone_tokens_used / metadata.phone_tokens_remaining — linkedin_to_mobile_phone only; no other tool reports phone tokens.

The HTTP status says whether the call completed. The body says what happened. Branch on status, not on the HTTP code.

Reading an outcome

Every call ends in one of three outcomes:

Outcome	HTTP	Body	Cost
Found	`200`	`status: "ok"` with populated `results`	Tokens charged
Not found	`200`	`status: "not_found"` with empty or `null` `results`	No tokens charged
Error	`4xx` / `5xx`	`error` object, no `results`	No tokens charged

A not-found is a normal result, not a failure. The tool ran, the lookup was clean, and the data simply isn’t on file for that input — so nothing is charged. It still counts as one request against your Fair Use requests limit.

{
  "results": {
    "email": null,
    "type": null,
    "last_validated_at": null
  },
  "status": "not_found",
  "metadata": {
    "fair_use": {
      "records_remaining_5h": 179999,
      "records_reset_5h": "2026-07-15T18:53:16Z",
      "records_remaining_1w": 899999,
      "records_reset_1w": "2026-07-22T13:53:16Z"
    }
  }
}

Batches behave the same way. A batch returns 200 and its body is the per-item report — each entry carries its own status, so a batch of 100 where 12 matched returns 12 hits and 88 misses in one 200. A batch where nothing matched is still 200 with status: "not_found", not an error.

This changed. Lookups that found nothing used to return 404. They now return 200 with status: "not_found", on single calls and batches alike. If your integration treats a 404 as “no data”, switch it to read status — the only 404 the API still returns is tool_not_found, meaning the tool name in the URL is unknown or retired.

Reading the outcome without parsing the body

Every tool response also carries an X-MoltSets-Outcome header — ok, not_found, or the error code. Proxies, log pipelines, and clients that would rather not parse JSON can branch on it directly. It is absent on requests that ran no tool, such as an auth failure.

Errors

Errors use a single shape on both REST and MCP:

{
  "error": {
    "code": "insufficient_tokens",
    "message": "You have 0 tokens remaining."
  }
}

Branch on error.code, not on the message text.

Code	HTTP	What it means	What to do
`invalid_input`	`422`	The body is malformed, or a parameter is missing, malformed, or outside its allowed values	Fix the parameter and retry. Retrying unchanged returns the same error
`unauthorized`	`401`	Missing, invalid, or revoked API key	Check the `Authorization` header, or issue a new key
`forbidden`	`403`	Missing `User-Agent` header	Add a `User-Agent` header — any non-empty value works
`account_inactive`	`403`	The account is not active	The account was canceled, by choice or because of a payment issue. Log in at app.moltsets.com and subscribe to a plan
`insufficient_tokens`	`402`	Token balance can’t cover the call	Top up or upgrade. On a batch, unaffordable items are dropped and the rest still return
`insufficient_phone_tokens`	`402`	Not enough phone tokens to cover a mobile result	Phone tokens come from a separate monthly subscription — see Phone tokens. Batches drop the excess rather than failing
`plan_restricted`	`403`	The tool isn’t part of your plan — today, the dedicated personal-email tools, and the ad-audience tools on the $397 and $997 plans	A plan condition: no `Retry-After`, and topping up tokens won’t clear it. For personal-email tools, use `linkedin_to_business_email` or contact support
`fair_use_limit_exceeded`	`429`	A Fair Use record window is exhausted — or, on the free tier, the one-time search trial	Wait for `metadata.retry_after` seconds. Where the limit is the free search trial there is no `Retry-After`, because that grant never refreshes
`fair_use_requests_exceeded`	`429`	The 5-hour request window is exhausted	Wait for `metadata.retry_after` seconds, then resume
`rate_limited`	`429`	Burst guard — too many requests too quickly	Back off and retry; see Handling rate limits
`search_concurrency_exceeded`	`429`	Too many `search_people` / `search_companies` calls running at the same time for your plan	Retry after 1 second (`Retry-After: 1`) and keep fewer searches running in parallel; see Concurrent searches
`tool_not_found`	`404`	The tool name in the URL is unknown or retired	Check the spelling against Available tools. This is the API’s only `404`
`internal_error`	`500`	The call couldn’t complete — usually the endpoint is temporarily unavailable, but an oversized request can also cause it	Try a smaller request first. If that also fails, requeue and retry later — see below

Nothing is charged on an error.

When a call returns a 500

A 500 with internal_error means the call couldn’t complete. Usually the endpoint is temporarily unavailable, but an unusually large or heavy request can also fail this way:

{
  "error": {
    "code": "internal_error",
    "message": "Unexpected connection error."
  },
  "metadata": {}
}

Try a smaller request first. If the call was a batch, split it into smaller batches and resend them. If the smaller requests succeed, keep your batches at that size. The MoltSets team is alerted automatically, so there’s no need to report it. If a smaller request fails too, the endpoint is temporarily unavailable. Resolution time varies, largely with when the outage starts: one that begins during office hours is picked up sooner than one overnight or over a weekend. Because of that, don’t build a fixed retry delay around it — treat it as a transient failure in your pipeline, not a bad record, and requeue the affected calls to retry later instead of looping on the endpoint. A later call succeeding is the signal that the endpoint is back.

Plans

Plan	Lifetime Tokens	Enrichment records	Search records
$0	1000	1k lifetime	100 lifetime (5 per call max)
$27 / month	Unlimited	1k / 5h · 5k / week	500 / 5h · 2.5k / week
$97 / month	Unlimited	15k / 5h · 75k / week	7.5k / 5h · 37.5k / week
$397 / month	Unlimited	150k / 5h · 750k / week	75k / 5h · 375k / week
$997 / month	Unlimited	225k / 5h · 1.125M / week	112.5k / 5h · 562.5k / week

Records are the data rows returned; requests are capped separately — see Rate Limits. Phone tokens for linkedin_to_mobile_phone aren’t included in any plan. They’re sold as a separate monthly subscription, available on paid plans only — see Phone tokens.

linkedin_to_personal_email_usa and linkedin_to_best_personal_email_usa are not available on every plan — access is set by price tier. Call get_account and read personal_email_available to know where yours stands. Both return US records only — non-US records are filtered out, so a non-US profile comes back as a not_found.Calls from an account without access return 403 with:

{
  "error": {
    "code": "plan_restricted",
    "message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
  }
}

Contact support@moltsets.com to request access.

email_to_maid, business_email_to_sha256, and linkedin_to_sha256 are not available on the $397 / month and $997 / month plans. Calls from those plans return 403 with plan_restricted. It’s a plan condition — retrying or topping up tokens won’t clear it.

Choosing a plan

The right plan depends on how fast you need results. Higher rate limits mean faster processing — the difference between waiting an hour and wrapping up in minutes.

Plan	Ideal for
$0	Exploring the API and testing integrations
$27 / month	Low-volume agents or early production use
$97 / month	Teams running identity resolution at scale
$397 / month	Growing teams that have outgrown the $97 plan’s throughput
$997 / month	High-throughput pipelines with sustained or unpredictable volume

More information

For more information on our plans, upgrading and downgrading processes, please refer to our support documentation at support.moltsets.com.

Available tools

Category	Tools
Search	`search_people`, `search_companies`, `search_linkedin_profile`, `search_business_email_by_name`, `search_business_profile_by_name`
Get Valid Emails	`linkedin_to_best_email`, `linkedin_to_business_email`, `linkedin_to_personal_email_usa` , `linkedin_to_best_personal_email_usa`
Get Carrier-Verified Mobile Phones	`linkedin_to_mobile_phone`
Reverse Lookups	`reverse_email_lookup`, `reverse_linkedin_lookup`
Get Ad Audience	`email_to_maid` †, `business_email_to_sha256` †, `linkedin_to_sha256` †
Get LinkedIn	`email_to_linkedin`
Get Company	`ip_to_company`
Account	`get_account`, `get_billing`, `get_usage`

* linkedin_to_personal_email_usa and linkedin_to_best_personal_email_usa are not available on every plan — access is set by price tier. Call get_account and read personal_email_available to know where yours stands. See Plans for the error they return. Without access, use linkedin_to_business_email instead.Both return US records only — non-US records are filtered out, so a non-US profile comes back as a not_found.

† Not available on the $397 / month and $997 / month plans. See Plans.

Switch to the _usa tools. The personal-email tools were previously named linkedin_to_personal_email and linkedin_to_best_personal_email. To migrate, add _usa to the end of the tool or route name — same data, same format, with non-US records now filtered out. The old names still work for now but will be retired in the near future — switch to the _usa names before then.

Getting Started

MoltSets' Data

Use Cases

Best Practices

Integrations

Base URL

How a request works

How a response works

Reading an outcome

Reading the outcome without parsing the body

Errors

When a call returns a 500

Plans

Choosing a plan

More information

Available tools

What to do next

Authentication

Rate Limits

​Base URL

​How a request works

​How a response works

​Reading an outcome

​Reading the outcome without parsing the body

​Errors

​When a call returns a 500

​Plans

​Choosing a plan

​More information

​Available tools

​What to do next

Authentication

Rate Limits

Base URL

How a request works

How a response works

Reading an outcome

Reading the outcome without parsing the body

Errors

When a call returns a 500

Plans

Choosing a plan

More information

Available tools

What to do next