ListMinerDocs

Getting startedOverview

Getting started

API reference

Send a company website. Get its decision makers and work emails back as JSON, from the same three sources and at the same rates as the app.

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.

Base URLhttps://api.prod.cold-email.softwaredoes.com/api/v1
Auth headerX-API-Key: YOUR_API_KEY
Keys live in the app, under API Keys.Get a key

Sources

  • WEBSITE_EMAILS
    Email addresses written on the company website (info@, sales@, people's addresses).
  • TEAM_PAGE
    People named on the company website (team and about pages) with their job title and work email.
  • LINKEDIN
    Decision makers matched on LinkedIn by job title, with their work email when one is found.

Endpoints

Authentication#

Every endpoint needs an API key in the X-API-Key header. Expired or invalid keys get a 401.

Header
X-API-Key: YOUR_API_KEY

Create an API key

  1. Create an account or log in.
  2. Open the API Keys section.
  3. Click Create and give the key a name, an optional description and an optional expiry (7, 30, 90, 180 or 365 days).
  4. 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.

Example body · POST /super-scraper
{
  "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

  • POST/super-scraperwithin 200 s
    One website, answer in the same request.
  • POST/batch/supersubmit, then collect
    Up to 25 websites per call. Collect with GET /batch/super/{job_id} when ready.

Fields both calls take

  • sourcesstring[]Required
    One or more of LINKEDIN, TEAM_PAGE, WEBSITE_EMAILS.
  • titlesstring[]
    Required with LINKEDIN or TEAM_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_namestring
    Required 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_companyinteger
    LinkedIn 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.

POST/api/v1/super-scraper
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"]}'
Response · 200 OK
{
  "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-KeyRequired
    Your API key.
  • Idempotency-Keystring, ≤ 200 chars
    Send 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

  • urlstringRequired
    A 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_type is Personal (a person's address) or Generic (info@, sales@). linkedin_match says how a LinkedIn person was matched: Domain, Exact company name or Company name (canonical).
  • results[].emailstring | null
    null for 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) or LINKEDIN_DATA_RELOADING (see LinkedIn data refresh).
  • errors[]object[]
    Why a source returned nothing; message is human-readable. See error codes.
  • tokens_spentinteger
    Tokens charged for this request.
  • tokens_remainedinteger
    Your balance after it.
  • partialobject | null
    Set 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.

POST/api/v1/batch/super
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"
Response · 202 Accepted
{ "job_id": "8b0e…", "status": "PROCESSING", "submitted_count": 2 }

Headers

  • Content-TypeRequired
    application/json
  • X-API-KeyRequired
    Your API key.

Body

  • itemsobject[]Required
    1–25 websites, each with url and company_name (required for every item when LINKEDIN is selected).
  • urlsstring[]
    Without LINKEDIN you may send "urls": ["acme-dental.com", "…"] instead of items.

Plus the fields both calls take.

Example body
{
  "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.

GET/api/v1/batch/super/{job_id}
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"
Response · 200 OK
{
  "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-KeyRequired
    Your API key.

Job status

  • PENDING, PROCESSING, FINALIZING
    Working. Poll again.
  • WAITING_LINKEDIN_DATA
    The monthly LinkedIn data refresh is running; linkedin shows reload_eta and gives_up_at. Poll again later; the job continues by itself.
  • COMPLETED, COMPLETED_WITH_ERRORS
    Done. COMPLETED_WITH_ERRORS means some websites or sources have errors, which is normal. Read results.
  • FAILED
    Nothing was charged; error explains. Resubmit, after a top-up if error says so.

Response

  • results[].resultsobject[]
    The same lines as Search one website. results[].errors explains each source without a result.
  • results[].heldboolean
    true: this website was not delivered and not charged because your balance ran out. partial then 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.

GET/api/v1/batch/balance
curl "https://api.prod.cold-email.softwaredoes.com/api/v1/batch/balance" \
  -H "X-API-Key: YOUR_API_KEY"
Response · 200 OK
{ "tokens_remained": 98 }

Headers

  • X-API-KeyRequired
    Your API key.

Pricing#

The API counts your credits as tokens: one token is one credit, at the same rates as the pricing card.

WhatTokens
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 emailFree
Failed requests, failed or cancelled jobs, sources that found nothingFree

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-scraper returns LINKEDIN_DATA_RELOADING for the LinkedIn source with reload.expected_completion_at. Nothing is charged for it, and the other sources answer normally.
  • Batches that include LinkedIn wait in WAITING_LINKEDIN_DATA and 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.

HTTPWhenWhat to do
400Bad RequestMore than 25 websites in one batchSplit the batch
401UnauthorizedMissing, unknown or expired API keyCheck X-API-Key
402Payment RequiredNot enough tokens to start (required_tokens_count, current_tokens_count)Top up
404Not FoundJob not found (wrong id, or older than 24 h); or Super Scraper not available for this account—
409ConflictSame Idempotency-Key still running; a source is temporarily switched offRetry later
422Validation ErrorInvalid request: missing titles, missing company name with LinkedIn, not a website address, bad country code, too many titles…Fix the request
429Too Many RequestsToo 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 GatewayEvery selected source failed for this website (nothing charged)Retry later
503Service UnavailableService busy or under maintenance (Retry-After may be set)Retry later

Common error_code values in errors[]

error_codeMeaning
NO_MATCHNo LinkedIn people for these titles
NO_TEAM_FOUNDThe website names no team
NO_EMAILS_FOUNDThe website shows no email addresses
NO_EMAIL_FOUND / NO_DELIVERABLE_EMAILSA person without a deliverable email
SITE_DEAD / SITE_BLOCKED / SITE_FETCH_FAILEDThe website could not be read
SOURCE_TIMEOUTThe source ran out of time
UNSUPPORTED_SHARED_PLATFORMfacebook.com/…, linktr.ee/… pages cannot be scraped
INVALID_URLNot a website address

Moving from the email and contacts endpoints#

The previous endpoints keep working. To get the same data from the Super Scraper:

BeforeNow
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/contactsPOST /batch/super with the matching sources
positionstitles

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.

esc

Nothing matches “”. Try a field name like titles or a status like 402.

↑↓ to move↵ to openesc to close