Overview#
Find decision makers and email addresses for company websites through one API. Choose the data you need per request, just like in the app. Send any combination of sources: a person found by several is returned once, with every source listed.
Sources
- WEBSITE_EMAILSEmail addresses written on the company website (
info@,sales@, people's addresses). - TEAM_PAGEPeople named on the company website (team and about pages) with their job title and work email.
- LINKEDINDecision makers matched on LinkedIn by job title, with their work email when one is found.
Endpoints
- POST/super-scraperOne website, answer in the same request.
- POST/batch/superSubmit up to 25 websites.
- Collect a batch when it is ready.
- Check your token balance.
Authentication#
Every endpoint needs an API key in the X-API-Key header. Expired or invalid keys get a 401.
X-API-Key: YOUR_API_KEYCreate an API key
- Create an account or log in.
- Open the API Keys section.
- Click Create and give the key a name, an optional description and an optional expiry (7, 30, 90, 180 or 365 days).
- Copy the key right away. The full key is shown only when it is created and on that key's own page.
Request fields#
Both ways to search take the same fields. Pick the call by how many websites you have and how you want the answer.
{
"url": "acme-dental.com",
"company_name": "Acme Dental",
"sources": ["LINKEDIN", "TEAM_PAGE", "WEBSITE_EMAILS"],
"titles": ["Owner", "Dentist"],
"exclude_titles": ["Assistant"],
"countries": ["US"],
"people_per_company": 3
}Choose the right call
- One website, answer in the same request.
- Up to 25 websites per call. Collect with
GET /batch/super/{job_id}when ready.
Fields both calls take
- sourcesstring[]RequiredOne or more of
LINKEDIN,TEAM_PAGE,WEBSITE_EMAILS. - titlesstring[]Required with
LINKEDINorTEAM_PAGE. Job titles to look for, up to 50 (e.g.["Owner", "CEO"]). Each title also finds its group (CEO ↔ Chief Executive Officer) and longer titles containing it ("Founder" finds "Co-Founder"). - company_namestringRequired with
LINKEDIN. The company's name, up to 500 characters; LinkedIn needs it to match people reliably. - exclude_titlesstring[]Words a returned title must never contain, as a whole word (e.g.
["Assistant", "Intern"]), up to 50. - countriesstring[]ISO 3166-1 alpha-2 codes (
US,GB); LinkedIn only; empty means any country. - people_per_companyintegerLinkedIn people per company, 1–20.
Default: 3
Search one website#
The Super Scraper searches every source you pick for one website and answers in the same request.
- Cost
- 1–2 tokens per email
- Answer
- Within 200 s
- Client timeout
- 210 s or more
- Limit
- 3 in flight per key
curl -X POST "https://api.prod.cold-email.softwaredoes.com/api/v1/super-scraper" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
--max-time 210 \
-d '{"url":"acme-dental.com","company_name":"Acme Dental","sources":["LINKEDIN","WEBSITE_EMAILS"],"titles":["Owner"]}'{
"url": "acme-dental.com",
"request_id": "6f1c2a9e-0d7b-4c3e-9f55-2b1d8e6a4c10",
"sources": {
"LINKEDIN": { "status": "OK", "error_code": null, "error": null, "reload": null },
"TEAM_PAGE": { "status": "NO_RESULT", "error_code": "NO_TEAM_FOUND", "error": "No team members matching the job titles", "reload": null },
"WEBSITE_EMAILS": { "status": "OK", "error_code": null, "error": null, "reload": null }
},
"results": [
{
"sources": ["LinkedIn", "Website"],
"full_name": "Jane Smith",
"position": "Owner",
"email": "jane@acme-dental.com",
"email_type": "Personal",
"linkedin_url": "https://www.linkedin.com/in/…",
"linkedin_match": "Domain"
},
{
"sources": ["Website"],
"full_name": null,
"position": null,
"email": "info@acme-dental.com",
"email_type": "Generic",
"linkedin_url": null,
"linkedin_match": null
}
],
"errors": [
{ "source": "Team page", "status": "no_result", "error_code": "NO_TEAM_FOUND",
"message": "No team members matching the job titles" }
],
"tokens_spent": 3,
"tokens_remained": 997,
"partial": null
}Headers
- Content-TypeRequired
application/json - X-API-KeyRequiredYour API key.
- Idempotency-Keystring, ≤ 200 charsSend a new value per search (a UUID works). Retrying with the same key and body returns the stored answer without charging again; keys are remembered for 24 hours. The same key with a different body returns
422; while the first request is still running,409.
Body
- urlstringRequiredA website address or a domain, up to 2,048 characters.
Plus the fields both calls take: sources, titles, company_name, exclude_titles, countries, people_per_company.
Response
- results[]object[]One line per person or inbox.
email_typeisPersonal(a person's address) orGeneric(info@, sales@).linkedin_matchsays how a LinkedIn person was matched:Domain,Exact company nameorCompany name (canonical). - results[].emailstring | null
nullfor a LinkedIn person whose email was not found; such lines are free. - sources.<SOURCE>.statusstring
OK,NO_RESULT,ERROR,TIMEOUT,DISABLED(source switched off for maintenance) orLINKEDIN_DATA_RELOADING(see LinkedIn data refresh). - errors[]object[]Why a source returned nothing;
messageis human-readable. See error codes. - tokens_spentintegerTokens charged for this request.
- tokens_remainedintegerYour balance after it.
- partialobject | nullSet when your balance covered only part of the result:
{ "lines_returned", "lines_held", "tokens_needed" }.
Submit a batch#
Submit a batch in one call, then collect the results when they are ready.
- Cost
- 1–2 tokens per email
- Batch size
- 1–25 websites
- Answer
- 202, then collect
- Limit
- 5 batches per account
JOB=$(curl -s -X POST "https://api.prod.cold-email.softwaredoes.com/api/v1/batch/super" \
-H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"items":[{"url":"acme-dental.com","company_name":"Acme Dental"},{"url":"brightsmiles.co.uk","company_name":"Bright Smiles"}],"sources":["LINKEDIN","TEAM_PAGE","WEBSITE_EMAILS"],"titles":["Owner","Dentist"]}' | jq -r .job_id)
curl -s "https://api.prod.cold-email.softwaredoes.com/api/v1/batch/super/$JOB?wait_seconds=25" \
-H "X-API-Key: YOUR_API_KEY"{ "job_id": "8b0e…", "status": "PROCESSING", "submitted_count": 2 }Headers
- Content-TypeRequired
application/json - X-API-KeyRequiredYour API key.
Body
- itemsobject[]Required1–25 websites, each with
urlandcompany_name(required for every item whenLINKEDINis selected). - urlsstring[]Without
LINKEDINyou may send"urls": ["acme-dental.com", "…"]instead ofitems.
Plus the fields both calls take.
{
"items": [
{ "url": "acme-dental.com", "company_name": "Acme Dental" },
{ "url": "brightsmiles.co.uk", "company_name": "Bright Smiles" }
],
"sources": ["LINKEDIN", "TEAM_PAGE", "WEBSITE_EMAILS"],
"titles": ["Owner", "Dentist"]
}Collect a batch#
wait_seconds (0–28) keeps the request open until the job finishes or the time runs out, so you can poll in a simple loop without sleeping. Any API key on the same account can read the job.
- Long poll
- Up to 28 s
- Results kept
- 24 hours
- Read by
- Any key on the account
curl -s "https://api.prod.cold-email.softwaredoes.com/api/v1/batch/super/JOB_ID?wait_seconds=25" \
-H "X-API-Key: YOUR_API_KEY"{
"job_id": "8b0e…",
"status": "COMPLETED",
"total_rows": 2,
"created_at": "2026-10-13T12:00:00+00:00",
"linkedin": null,
"tokens_spent": 9,
"results": [
{
"url": "acme-dental.com",
"company_name": "Acme Dental",
"sources": { "LINKEDIN": { "status": "OK", "error_code": null, "error": null, "reload": null }, "…": {} },
"results": [ { "sources": ["LinkedIn"], "full_name": "Jane Smith", "position": "Owner",
"email": "jane@acme-dental.com", "email_type": "Personal",
"linkedin_url": "https://www.linkedin.com/in/…", "linkedin_match": "Domain" } ],
"errors": [],
"held": false
}
],
"error": null,
"failure_reason": null,
"retrying": false,
"partial": null
}Headers
- X-API-KeyRequiredYour API key.
Job status
- PENDING, PROCESSING, FINALIZINGWorking. Poll again.
- WAITING_LINKEDIN_DATAThe monthly LinkedIn data refresh is running;
linkedinshowsreload_etaandgives_up_at. Poll again later; the job continues by itself. - COMPLETED, COMPLETED_WITH_ERRORSDone.
COMPLETED_WITH_ERRORSmeans some websites or sources have errors, which is normal. Readresults. - FAILEDNothing was charged;
errorexplains. Resubmit, after a top-up iferrorsays so.
Response
- results[].resultsobject[]The same lines as Search one website.
results[].errorsexplains each source without a result. - results[].heldboolean
true: this website was not delivered and not charged because your balance ran out.partialthen shows{ "websites_returned", "websites_held", "tokens_needed" }. - retryingboolean
true: email verification is briefly unavailable and the job is retrying by itself.
Check balance#
Returns your account's remaining token balance. It costs nothing and does not count toward job-submission limits.
curl "https://api.prod.cold-email.softwaredoes.com/api/v1/batch/balance" \
-H "X-API-Key: YOUR_API_KEY"{ "tokens_remained": 98 }Headers
- X-API-KeyRequiredYour API key.
Pricing#
The API counts your credits as tokens: one token is one credit, at the same rates as the pricing card.
| What | Tokens |
|---|---|
| A person with a work email (LinkedIn or team page) | 2 |
| An email address found on the website (also when it belongs to a person found by another source) | 1 |
| A person without an email | Free |
| Failed requests, failed or cancelled jobs, sources that found nothing | Free |
Each email is charged once per request or batch. A request needs at least 5 tokens on the balance to start; if the balance covers only part of the result you receive that part (partial, held). Check your balance at any time.
LinkedIn data refresh#
The LinkedIn data is rebuilt once a month. While it runs:
POST /super-scraperreturnsLINKEDIN_DATA_RELOADINGfor the LinkedIn source withreload.expected_completion_at. Nothing is charged for it, and the other sources answer normally.- Batches that include LinkedIn wait in
WAITING_LINKEDIN_DATAand continue by themselves. After 24 hours the affected websites are returned with an error and not charged.
Errors#
Error bodies always have detail, a message. For validation errors it is a string; for malformed JSON it is a list of {loc, msg} objects.
| HTTP | When | What to do |
|---|---|---|
| 400Bad Request | More than 25 websites in one batch | Split the batch |
| 401Unauthorized | Missing, unknown or expired API key | Check X-API-Key |
| 402Payment Required | Not enough tokens to start (required_tokens_count, current_tokens_count) | Top up |
| 404Not Found | Job not found (wrong id, or older than 24 h); or Super Scraper not available for this account | — |
| 409Conflict | Same Idempotency-Key still running; a source is temporarily switched off | Retry later |
| 422Validation Error | Invalid request: missing titles, missing company name with LinkedIn, not a website address, bad country code, too many titles… | Fix the request |
| 429Too Many Requests | Too many requests at once (up to 3 single-website requests in flight per API key; up to 5 batches running per account) | Wait for Retry-After seconds |
| 502Bad Gateway | Every selected source failed for this website (nothing charged) | Retry later |
| 503Service Unavailable | Service busy or under maintenance (Retry-After may be set) | Retry later |
Common error_code values in errors[]
| error_code | Meaning |
|---|---|
NO_MATCH | No LinkedIn people for these titles |
NO_TEAM_FOUND | The website names no team |
NO_EMAILS_FOUND | The website shows no email addresses |
NO_EMAIL_FOUND / NO_DELIVERABLE_EMAILS | A person without a deliverable email |
SITE_DEAD / SITE_BLOCKED / SITE_FETCH_FAILED | The website could not be read |
SOURCE_TIMEOUT | The source ran out of time |
UNSUPPORTED_SHARED_PLATFORM | facebook.com/…, linktr.ee/… pages cannot be scraped |
INVALID_URL | Not a website address |
Moving from the email and contacts endpoints#
The previous endpoints keep working. To get the same data from the Super Scraper:
| Before | Now |
|---|---|
POST /scrape-emails (one website) | POST /super-scraper with "sources": ["WEBSITE_EMAILS"] |
POST /scrape-contacts (one website, positions) | POST /super-scraper with "sources": ["TEAM_PAGE"] and "titles" |
POST /batch/emails, POST /batch/contacts | POST /batch/super with the matching sources |
positions | titles |
Prices are the same (1 token per website email, 2 per person's email). What changes is one merged answer across sources, and the sources and email_type fields on every line.