Lead Finder

Search Emailchaser's B2B contact database for free, then add the people you want to a campaign. Adding people reveals their details and spends credits.

get /lead-finder/filters Get Lead Finder filter values and limits get /lead-finder/imports List Lead Finder imports post /lead-finder/imports Add people to a campaign from the contact database (spends credits and metered verification)get /lead-finder/imports/{id} Get a Lead Finder import post /lead-finder/imports/{id}/cancel Cancel a Lead Finder import post /lead-finder/searches Search the contact database (free, masked results)get /lead-finder/searches/{id} Get a Lead Finder search

Get Lead Finder filter values and limits

get https://api.emailchaser.com/r/lead-finder/filters

Works with a read-only key

Returns the values the enum filters accept (seniorities, job functions, company sizes, revenue bands, industries, countries, headquarters countries, regions and continents), the limits that apply to this workspace (page sizes, deepest page, refs per import, first-N count, running imports, and the daily browsing allowance with what is left of it today), and creditsPerProspect, what adding one person to a campaign costs. Free: no call to the data provider is made.

Responses

200 Filter vocabulary, limits and price · LeadFinderFilters
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 plan_required: the workspace's plan does not include Lead Finder · LeadFinderError
409 provider_unavailable: the contact database is switched off · LeadFinderError
500 internal · LeadFinderError

Fields in the 200 response

companySizes array of string
continents array of string
countries array of string
creditsPerProspect integer
CreditsPerProspect is what adding one person to a campaign costs, read from the pricing table at request time.
Example: 1
headquartersCountries array of string
industries array of string
jobFunctions array of string
limits LeadFinderLimits
14 fields inside limits
- defaultPageSize integer
  Example: 25
- maxChipsPerField integer
  Example: 50
- maxDomainsPerField integer
  Example: 1000
- maxFirstN integer
  Example: 5000
- maxPage integer
  Example: 100
- maxRefsPerImport integer
  Example: 1000
- maxRunningImports integer
  Example: 3
- maxSavedSearchName integer
  Example: 80
- maxSavedSearches integer
  MaxSavedSearches and MaxSavedSearchName bound the searches a workspace saves in the app, and TopUpHourUTC is the hour of the day, in UTC, a saved search's weekly top-up runs.
  Example: 100
- maxValueLength integer
  Example: 100
- pageSizes array of integer
  Example: [25,50]
- rowsLeftToday integer
  RowsLeftToday is what is left of it this UTC day.
  Example: 1950
- rowsPerDay integer
  RowsPerDay is the account's daily browsing allowance in result rows.
  Example: 2000
- topUpHourUtc integer
  Example: 14
regions array of string
revenue array of string
seniorities array of string

Request

curl -X GET "https://api.emailchaser.com/r/lead-finder/filters" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "companySizes": [
    "string"
  ],
  "continents": [
    "string"
  ],
  "countries": [
    "string"
  ],
  "creditsPerProspect": 1,
  "headquartersCountries": [
    "string"
  ],
  "industries": [
    "string"
  ],
  "jobFunctions": [
    "string"
  ],
  "limits": {
    "defaultPageSize": 25,
    "maxChipsPerField": 50,
    "maxDomainsPerField": 1000,
    "maxFirstN": 5000,
    "maxPage": 100,
    "maxRefsPerImport": 1000,
    "maxRunningImports": 3,
    "maxSavedSearchName": 80,
    "maxSavedSearches": 100,
    "maxValueLength": 100,
    "pageSizes": [
      25,
      50
    ],
    "rowsLeftToday": 1950,
    "rowsPerDay": 2000,
    "topUpHourUtc": 14
  },
  "regions": [
    "string"
  ],
  "revenue": [
    "string"
  ],
  "seniorities": [
    "string"
  ]
}

List Lead Finder imports

get https://api.emailchaser.com/r/lead-finder/imports

Works with a read-only key

Lists the workspace's Lead Finder imports, newest first, with their progress. Imports keep being listed after a plan change, so a workspace can always see what it started.

Parameters

limit integer in query
How many imports to return, 1 to 50 (default 10)

Responses

200 Recent imports · LeadFinderImports
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
500 internal · LeadFinderError

Fields in the 200 response

imports array of LeadFinderImport
21 fields inside imports
- added integer
  Example: 22
- audienceKey string
  AudienceKey names the filters the people came from, as on a search.
- campaignId integer
  Example: 123
- campaignName string
  Example: Irish sales leaders
- createdAt string
- creditsPerProspect integer
  Example: 1
- creditsSpent integer
  CreditsSpent is what the import has charged so far. People added while the workspace's credits were free add nothing to it.
  Example: 22
- endReason string
  EndReason says how an import ended: all_selected or requested_reached (finished), audience_exhausted or fetch_limit (a first_n import stopped early), or canceled. A failed import has none; see LastError.
- expired integer
  Example: 0
- finishedAt string
- importId integer
  Example: 8812
- lastError string
  LastError says why a failed import stopped: insufficient_credits, contact_cap_reached, results_expired, budget_exhausted, provider_blocked, provider_unavailable (the people database was down or in maintenance; start the import again later), rate_limited, invalid_filters, campaign_not_found or internal. A failed import can still have added and charged people.
- mode string
  Example: selected
- requested integer
  Example: 25
- skipReasons map of integer
  SkipReasons counts skipped people by reason: already_in_workspace, blocklisted, reveal_returned_no_address, consumer_mailbox, invalid_email or contact_cap_reached.
- skipped integer
  Example: 3
- startsAt integer
  StartsAt is the position in the results a first_n import started from.
  Example: 201
- status string
  Status is running, completed, failed or canceled. Added, CreditsSpent and Status can still change until FinishedAt is set.
  Example: completed
- topUpOf integer
  TopUpOf is set on an import a saved search's weekly top-up started (set up in the app): the saved search's id.
- verification LeadFinderVerification
- verifyEmails boolean
  Example: true

Request

curl -X GET "https://api.emailchaser.com/r/lead-finder/imports" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "imports": [
    {
      "added": 22,
      "audienceKey": "string",
      "campaignId": 123,
      "campaignName": "Irish sales leaders",
      "createdAt": "string",
      "creditsPerProspect": 1,
      "creditsSpent": 22,
      "endReason": "string",
      "expired": 0,
      "finishedAt": "string",
      "importId": 8812,
      "lastError": "string",
      "mode": "selected",
      "requested": 25,
      "skipReasons": {
        "key": 123
      },
      "skipped": 3,
      "startsAt": 201,
      "status": "completed",
      "topUpOf": 123,
      "verification": {
        "catchAll": 2,
        "invalid": 1,
        "limitReached": 0,
        "unknown": 0,
        "valid": 20
      },
      "verifyEmails": true
    }
  ]
}

Add people to a campaign from the contact database (spends credits and metered verification)

post https://api.emailchaser.com/r/lead-finder/imports

Needs a read and write key

SPENDS CREDITS, AND BY DEFAULT METERED VERIFICATION. Reveals people from the contact database and adds them to a campaign as leads, in the background. mode=selected adds the people named by refs from search results (1 to 1,000; a ref that is no longer stored is counted in expired and dropped). mode=first_n adds up to count people matching filters who are not in the workspace yet (1 to 5,000). It continues after the last first_n import of the same filters (startsAt in the response says where; fromStart true starts from the top instead) and skips people already in the workspace for free, so repeating a first_n call adds and charges for the next count people: never repeat a call to retry, read GET /lead-finder/imports first. While a first_n import of the same filters is still running another is refused (409 import_running). It stops early when the audience runs out (endReason audience_exhausted, and the next first_n import of those filters starts from the top again) or once it has looked at five people for every one requested, at least 1,000 (endReason fetch_limit, and the next one continues from there). People already in the workspace that it passes count toward that limit although they cost nothing. Every person it looks at, added or skipped, also counts against the account's daily first_n allowance (25,000 people a UTC day by default). Each person added costs creditsPerProspect credits (1 at the time of writing). People already in the workspace, blocklisted, without a usable address, on a personal mailbox when the campaign only takes business addresses, or marked invalid by verification are skipped and cost no credits. verifyEmails (default true) checks every screened address with the paid verification waterfall of POST /email-verification/jobs, including the ones it marks invalid: one check when the first provider rejects the address and two otherwise, billed as metered usage on the next invoice at the GET /email-verification/rates price, within the account's monthly verification allowance. Catch-all and unconfirmed addresses are added and charged, and so is every address once that allowance is used up. Set verifyEmails to false to skip verification. The wallet must hold estimatedCredits for the import to start. Credits are held batch by batch and settled against the leads actually created. Leads added to a running or paused campaign get their emails at once (a paused campaign sends them when resumed); adding to a completed campaign resumes it, so it starts sending again; in a draft campaign the emails are created at launch. At most 3 imports run at once in a workspace. Poll GET /lead-finder/imports/{id} until finishedAt is set. Needs a read_write key.

Request bodyJSON · LeadFinderImportRequest

campaignId integer
CampaignID is the campaign the people are added to.
Example: 123
count integer
Count is how many people to add, for mode first_n: 1 to 5,000.
Example: 200
filters LeadFinderFilterSet
Filters are the filters to add from, for mode first_n. At least one include filter is required; the rules are those of a search. For mode selected they are optional: the search the refs came from, so the people count towards what those filters have added (progress on a search).
21 fields inside filters
- cities array of string
  Example: ["Dublin"]
- companyKeywords string
  CompanyKeywords is one phrase matched against what the employer does.
- companyName string
  CompanyName is one phrase matched against the employer's name.
- companySizes array of string
  CompanySizes are headcount bands from GET /lead-finder/filters.
  Example: ["51 to 200"]
- continents array of string
- countries array of string
  Countries, Regions and Continents are values from GET /lead-finder/filters, where the person is. Use one of the three at a time.
  Example: ["Ireland"]
- domains array of string
  Domains and ExcludeDomains are company domains, up to 1,000 each.
  Example: ["acme.com"]
- excludeCountries array of string
- excludeDomains array of string
- excludeHeadquartersCountries array of string
- excludeIndustries array of string
- excludeJobTitles array of string
  Example: ["Intern"]
- headquartersCountries array of string
  HeadquartersCountries are where the employer is headquartered.
- industries array of string
  Industries are values from GET /lead-finder/filters.
  Example: ["Software Development"]
- jobFunctions array of string
  JobFunctions are values from GET /lead-finder/filters.
  Example: ["Sales & Business Development"]
- jobTitles array of string
  JobTitles are free text, matched as OR terms.
  Example: ["Head of Sales","VP Sales"]
- regions array of string
- revenue array of string
  Revenue is revenue bands from GET /lead-finder/filters.
- seniorities array of string
  Seniorities are values from GET /lead-finder/filters.
  Example: ["Director"]
- states array of string
  States and Cities are free text, matched inside the person's location.
- technologies array of string
  Technologies are free text: tools the employer uses.
  Example: ["HubSpot"]
fromStart boolean
FromStart makes a first_n import start from the top of the results instead of after the last first_n import of the same filters.
Example: false
mode string
Mode is "selected" (add the people named in Refs) or "first_n" (add up to Count people matching Filters who are not in the workspace yet, continuing after the last first_n import of the same filters).
One of: "selected", "first_n". Example: selected
refs array of string
Refs are result refs from searches, for mode selected: 1 to 1,000.
Example: ["r_Q2x9LmVwZ3JhY2VIb3BwZX"]
verifyEmails boolean
VerifyEmails checks each address with the paid verification waterfall before it is added: one or two metered checks per address, billed on the next invoice (GET /email-verification/rates), including addresses that turn out invalid. Invalid addresses are skipped and cost no credits; catch-all and unconfirmed ones are added and charged, and so is every address once the monthly verification allowance is used up. Defaults to true.
Example: true

Responses

202 Import started · LeadFinderImportCreated
400 invalid_request (mode, refs or count) or invalid_filters · LeadFinderError
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
402 insufficient_credits: needed and available are in credits; buy more with POST /credits/purchase · LeadFinderError
403 plan_required, or a read-only key: the auth layer refuses it as text/plain, error 'This API key is read-only; this endpoint requires the read_write scope' · LeadFinderError
404 campaign_not_found · LeadFinderError
409 provider_unavailable: the contact database is switched off; or import_running: a first_n import of the same filters is still running (importId), start this one when it has finished · LeadFinderError
410 results_expired: none of the refs is still stored; search again · LeadFinderError
422 contact_cap_reached: the import would pass the plan's contact limit · LeadFinderError
429 rate_limited (reason running_imports) or budget_exhausted (reason daily_import_limit, daily_budget, monthly_budget or fair_use_floor): retry after retryAfterSeconds · LeadFinderError
500 internal · LeadFinderError

Fields in the 202 response

audienceKey string
AudienceKey names the import's filters, as on a search.
available integer
Available is the wallet's spendable balance when the import started. While the workspace's credits are free (unlimited on GET /credits/balance) it is the workspace's own balance, which the import does not use.
Example: 4975
creditsPerProspect integer
Example: 1
estimatedCredits integer
EstimatedCredits is Requested x CreditsPerProspect, the most this import can cost in credits. Skipped people cost no credits; metered verification is billed separately.
Example: 25
expired integer
Expired counts refs that were no longer stored and were dropped.
Example: 0
importId integer
Example: 8812
requested integer
Requested is how many people the import will try to add.
Example: 25
startsAt integer
StartsAt is the position in the results a first_n import starts from: 1 is the first person. Left out for a selected import.
Example: 201
status string
Example: running

Request

curl -X POST "https://api.emailchaser.com/r/lead-finder/imports" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": 123,
  "count": 200,
  "filters": {
    "cities": [
      "Dublin"
    ],
    "companyKeywords": "string",
    "companyName": "Acme",
    "companySizes": [
      "51 to 200"
    ],
    "continents": [
      "string"
    ],
    "countries": [
      "Ireland"
    ],
    "domains": [
      "acme.com"
    ],
    "excludeCountries": [
      "string"
    ],
    "excludeDomains": [
      "string"
    ],
    "excludeHeadquartersCountries": [
      "string"
    ],
    "excludeIndustries": [
      "string"
    ],
    "excludeJobTitles": [
      "Intern"
    ],
    "headquartersCountries": [
      "string"
    ],
    "industries": [
      "Software Development"
    ],
    "jobFunctions": [
      "Sales & Business Development"
    ],
    "jobTitles": [
      "Head of Sales",
      "VP Sales"
    ],
    "regions": [
      "string"
    ],
    "revenue": [
      "string"
    ],
    "seniorities": [
      "Director"
    ],
    "states": [
      "string"
    ],
    "technologies": [
      "HubSpot"
    ]
  },
  "fromStart": false,
  "mode": "selected",
  "refs": [
    "r_Q2x9LmVwZ3JhY2VIb3BwZX"
  ],
  "verifyEmails": true
}'

Response

{
  "audienceKey": "string",
  "available": 4975,
  "creditsPerProspect": 1,
  "estimatedCredits": 25,
  "expired": 0,
  "importId": 8812,
  "requested": 25,
  "startsAt": 201,
  "status": "running"
}

Get a Lead Finder import

get https://api.emailchaser.com/r/lead-finder/imports/{id}

Works with a read-only key

Returns one import's progress: how many people were added and skipped and why, what verification said, and the credits spent so far. Status is running, completed, failed or canceled, and added, creditsSpent and status can still change until finishedAt is set. A completed import's endReason is all_selected, requested_reached, audience_exhausted or fetch_limit; a canceled one's is canceled. A failed import has no endReason but can still have added and charged people: lastError says why it stopped (insufficient_credits, contact_cap_reached, results_expired, budget_exhausted, provider_blocked, invalid_filters, campaign_not_found or internal). A new first_n import to finish a partial one starts from the top again and counts the people already added toward its fetch limit, so it only reaches new people while those fit inside five times its count (at least 1,000); otherwise pick the missing people by ref from search results. Imports belonging to other workspaces are reported as not found.

Parameters

id integer required in path
Import ID (importId)

Responses

200 The import · LeadFinderImport
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
404 not_found · LeadFinderError
500 internal · LeadFinderError

Fields in the 200 response

added integer
Example: 22
audienceKey string
AudienceKey names the filters the people came from, as on a search.
campaignId integer
Example: 123
campaignName string
Example: Irish sales leaders
createdAt string
creditsPerProspect integer
Example: 1
creditsSpent integer
CreditsSpent is what the import has charged so far. People added while the workspace's credits were free add nothing to it.
Example: 22
endReason string
EndReason says how an import ended: all_selected or requested_reached (finished), audience_exhausted or fetch_limit (a first_n import stopped early), or canceled. A failed import has none; see LastError.
expired integer
Example: 0
finishedAt string
importId integer
Example: 8812
lastError string
LastError says why a failed import stopped: insufficient_credits, contact_cap_reached, results_expired, budget_exhausted, provider_blocked, provider_unavailable (the people database was down or in maintenance; start the import again later), rate_limited, invalid_filters, campaign_not_found or internal. A failed import can still have added and charged people.
mode string
Example: selected
requested integer
Example: 25
skipReasons map of integer
SkipReasons counts skipped people by reason: already_in_workspace, blocklisted, reveal_returned_no_address, consumer_mailbox, invalid_email or contact_cap_reached.
skipped integer
Example: 3
startsAt integer
StartsAt is the position in the results a first_n import started from.
Example: 201
status string
Status is running, completed, failed or canceled. Added, CreditsSpent and Status can still change until FinishedAt is set.
Example: completed
topUpOf integer
TopUpOf is set on an import a saved search's weekly top-up started (set up in the app): the saved search's id.
verification LeadFinderVerification
5 fields inside verification
- catchAll integer
  Example: 2
- invalid integer
  Example: 1
- limitReached integer
  Example: 0
- unknown integer
  Example: 0
- valid integer
  Example: 20
verifyEmails boolean
Example: true

Request

curl -X GET "https://api.emailchaser.com/r/lead-finder/imports/123" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "added": 22,
  "audienceKey": "string",
  "campaignId": 123,
  "campaignName": "Irish sales leaders",
  "createdAt": "string",
  "creditsPerProspect": 1,
  "creditsSpent": 22,
  "endReason": "string",
  "expired": 0,
  "finishedAt": "string",
  "importId": 8812,
  "lastError": "string",
  "mode": "selected",
  "requested": 25,
  "skipReasons": {
    "key": 123
  },
  "skipped": 3,
  "startsAt": 201,
  "status": "completed",
  "topUpOf": 123,
  "verification": {
    "catchAll": 2,
    "invalid": 1,
    "limitReached": 0,
    "unknown": 0,
    "valid": 20
  },
  "verifyEmails": true
}

Cancel a Lead Finder import

post https://api.emailchaser.com/r/lead-finder/imports/{id}/cancel

Needs a read and write key

Marks a running import canceled at once and stops it after the batch it is working on. A batch the worker is already writing is still added and charged; a batch still being screened or verified is dropped, though verification checks already made are billed. Credits held for the rest are released. Until finishedAt is set, added, creditsSpent and even status can still change: if that batch was the import's last, it ends completed or failed instead. A canceled import cannot be resumed. Canceling an import that has already finished changes nothing and returns it as it is. Needs a read_write key.

Parameters

id integer required in path
Import ID (importId)

Responses

200 The import, as it stands · LeadFinderImport
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 A read-only key: the auth layer refuses it as text/plain, error 'This API key is read-only; this endpoint requires the read_write scope' · LeadFinderError
404 not_found · LeadFinderError
500 internal · LeadFinderError

Fields in the 200 response

added integer
Example: 22
audienceKey string
AudienceKey names the filters the people came from, as on a search.
campaignId integer
Example: 123
campaignName string
Example: Irish sales leaders
createdAt string
creditsPerProspect integer
Example: 1
creditsSpent integer
CreditsSpent is what the import has charged so far. People added while the workspace's credits were free add nothing to it.
Example: 22
endReason string
EndReason says how an import ended: all_selected or requested_reached (finished), audience_exhausted or fetch_limit (a first_n import stopped early), or canceled. A failed import has none; see LastError.
expired integer
Example: 0
finishedAt string
importId integer
Example: 8812
lastError string
LastError says why a failed import stopped: insufficient_credits, contact_cap_reached, results_expired, budget_exhausted, provider_blocked, provider_unavailable (the people database was down or in maintenance; start the import again later), rate_limited, invalid_filters, campaign_not_found or internal. A failed import can still have added and charged people.
mode string
Example: selected
requested integer
Example: 25
skipReasons map of integer
SkipReasons counts skipped people by reason: already_in_workspace, blocklisted, reveal_returned_no_address, consumer_mailbox, invalid_email or contact_cap_reached.
skipped integer
Example: 3
startsAt integer
StartsAt is the position in the results a first_n import started from.
Example: 201
status string
Status is running, completed, failed or canceled. Added, CreditsSpent and Status can still change until FinishedAt is set.
Example: completed
topUpOf integer
TopUpOf is set on an import a saved search's weekly top-up started (set up in the app): the saved search's id.
verification LeadFinderVerification
5 fields inside verification
- catchAll integer
  Example: 2
- invalid integer
  Example: 1
- limitReached integer
  Example: 0
- unknown integer
  Example: 0
- valid integer
  Example: 20
verifyEmails boolean
Example: true

Request

curl -X POST "https://api.emailchaser.com/r/lead-finder/imports/123/cancel" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "added": 22,
  "audienceKey": "string",
  "campaignId": 123,
  "campaignName": "Irish sales leaders",
  "createdAt": "string",
  "creditsPerProspect": 1,
  "creditsSpent": 22,
  "endReason": "string",
  "expired": 0,
  "finishedAt": "string",
  "importId": 8812,
  "lastError": "string",
  "mode": "selected",
  "requested": 25,
  "skipReasons": {
    "key": 123
  },
  "skipped": 3,
  "startsAt": 201,
  "status": "completed",
  "topUpOf": 123,
  "verification": {
    "catchAll": 2,
    "invalid": 1,
    "limitReached": 0,
    "unknown": 0,
    "valid": 20
  },
  "verifyEmails": true
}

Search the contact database (free, masked results)

post https://api.emailchaser.com/r/lead-finder/searches

Works with a read-only key

Searches Emailchaser's B2B contact database with explicit filters and returns one page of matching people, masked: first name, last initial, title, seniority, job function, company name, industry, size and revenue band, a company logo (logoUrl, an image this API serves, whose URL does not contain the company's domain), and city, state and country. No email address, email or company domain, LinkedIn URL or phone number is ever returned: contact details are revealed only by adding people to a campaign with POST /lead-finder/imports. Searching spends no credits, but every result row counts against the account's daily browsing allowance (limits.rowsPerDay in GET /lead-finder/filters, 2,000 rows a UTC day by default and 250 on a trial; rowsLeftToday shows what is left). An account may start 20 searches a minute. Searches that find nobody also draw on a bucket of 120 that refills at one every 30 seconds; while it is empty, every new search is refused with rate_limited (reason empty_searches) until the next refill, usually within 30 seconds. The same page asked for again within 10 minutes comes from cache and spends nothing. The request waits up to about six seconds: 200 means the search finished (status done, or failed with error saying why, for example rate_limited when the shared request budget is busy), 202 means it is still running, so read it with GET /lead-finder/searches/{id} using the returned searchId. total is exact when totalIsExact is true; otherwise it is a lower bound until totalStatus is done. inWorkspace marks people Lead Finder added to this workspace whose lead is still there, so adding them again would be skipped for free. Each person's ref stays valid for 60 minutes after the page it came on was last shown. A read-only key may call this endpoint.

Request bodyJSON · LeadFinderSearchRequest

filters LeadFinderFilterSet
Filters: at least one include filter is required. Enum fields take values from GET /lead-finder/filters. Free-text fields take up to 50 values of up to 100 characters each, and a value holding commas is split into one term per comma. Use only one of countries, regions and continents; states and cities go with countries or on their own. A broken rule is a 400 invalid_filters naming the field, value and reason.
21 fields inside filters
- cities array of string
  Example: ["Dublin"]
- companyKeywords string
  CompanyKeywords is one phrase matched against what the employer does.
- companyName string
  CompanyName is one phrase matched against the employer's name.
- companySizes array of string
  CompanySizes are headcount bands from GET /lead-finder/filters.
  Example: ["51 to 200"]
- continents array of string
- countries array of string
  Countries, Regions and Continents are values from GET /lead-finder/filters, where the person is. Use one of the three at a time.
  Example: ["Ireland"]
- domains array of string
  Domains and ExcludeDomains are company domains, up to 1,000 each.
  Example: ["acme.com"]
- excludeCountries array of string
- excludeDomains array of string
- excludeHeadquartersCountries array of string
- excludeIndustries array of string
- excludeJobTitles array of string
  Example: ["Intern"]
- headquartersCountries array of string
  HeadquartersCountries are where the employer is headquartered.
- industries array of string
  Industries are values from GET /lead-finder/filters.
  Example: ["Software Development"]
- jobFunctions array of string
  JobFunctions are values from GET /lead-finder/filters.
  Example: ["Sales & Business Development"]
- jobTitles array of string
  JobTitles are free text, matched as OR terms.
  Example: ["Head of Sales","VP Sales"]
- regions array of string
- revenue array of string
  Revenue is revenue bands from GET /lead-finder/filters.
- seniorities array of string
  Seniorities are values from GET /lead-finder/filters.
  Example: ["Director"]
- states array of string
  States and Cities are free text, matched inside the person's location.
- technologies array of string
  Technologies are free text: tools the employer uses.
  Example: ["HubSpot"]
page integer
Page is 1-based, up to limits.maxPage. Defaults to 1.
Example: 1
pageSize integer
PageSize is 25 (the default) or 50.
Example: 25

Responses

200 Search finished (status done or failed) · LeadFinderSearch
202 Search still running: read it with GET /lead-finder/searches/{id} · LeadFinderSearch
400 invalid_filters (field, value and reason name the problem) or invalid_request (page or pageSize) · LeadFinderError
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 plan_required: the workspace's plan does not include Lead Finder · LeadFinderError
409 provider_unavailable: the contact database is switched off · LeadFinderError
429 rate_limited (reason searches_per_minute, empty_searches or daily_preview_limit) or budget_exhausted (reason daily_budget, monthly_budget or fair_use_floor): retry after retryAfterSeconds, also sent as a Retry-After header · LeadFinderError
500 internal · LeadFinderError

Fields in the 200 response

audienceKey string
AudienceKey names the filters: the same picks in any order give the same key. Imports from these filters carry it too.
Example: 4f1c0e9a2b7d4c3e8f6a5b1d0c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e
creditsPerProspect integer
Example: 1
error string
Error is set on a failed search: rate_limited, provider_blocked, provider_unavailable (the people database is down or in maintenance; try again later), timeout, invalid_filters, budget_exhausted, expired or internal.
hasMore boolean
Example: true
maxPage integer
Example: 100
message string
page integer
Example: 1
pageSize integer
Example: 25
progress LeadFinderProgress
Progress is what earlier imports from these filters did in the workspace. Left out before the first one.
5 fields inside progress
- added integer
  Added is how many people they added.
  Example: 1000
- adds integer
  Adds is how many imports there were, selected ones included.
  Example: 2
- lastAddAt string
  LastAddAt is when the latest import from these filters started.
- nextFrom integer
  NextFrom is the position in the results (1 is the first person) the next first_n import of these filters starts from.
  Example: 901
- runningImportId integer
  RunningImportID is a first_n import of these filters still running. Another first_n import of the same filters is refused (409 import_running) until it ends.
  Example: 8813
results array of LeadFinderPerson
Results are the people on this page, masked.
9 fields inside results
- company LeadFinderPersonCompany
- firstName string
  Example: Grace
- inWorkspace boolean
  InWorkspace is true for someone Lead Finder added to this workspace whose lead is still there, so adding them again is skipped for free. A person who is a lead from another source shows false; adding them is still skipped and costs nothing.
  Example: false
- jobFunction string
  Example: Sales & Business Development
- lastInitial string
  Example: H
- location LeadFinderPersonLocation
- ref string
  Ref identifies the person for POST /lead-finder/imports. It stays valid for 60 minutes after the page it came on was last shown.
  Example: r_Q2x9LmVwZ3JhY2VIb3BwZX
- seniority string
  Example: Director
- title string
  Example: Head of Sales
rowsLeftToday integer
RowsLeftToday is the account's browsing allowance left this UTC day.
Example: 1975
searchId string
Example: s_c32d55f8dbd501c71bea43ee
status string
Status is running, done or failed.
Example: done
total integer
Total is how many people match; TotalIsExact says whether it is a count or a lower bound, and TotalStatus whether the count has landed (pending, done or failed).
Example: 2147
totalIsExact boolean
Example: true
totalStatus string
Example: done

Request

curl -X POST "https://api.emailchaser.com/r/lead-finder/searches" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {
    "cities": [
      "Dublin"
    ],
    "companyKeywords": "string",
    "companyName": "Acme",
    "companySizes": [
      "51 to 200"
    ],
    "continents": [
      "string"
    ],
    "countries": [
      "Ireland"
    ],
    "domains": [
      "acme.com"
    ],
    "excludeCountries": [
      "string"
    ],
    "excludeDomains": [
      "string"
    ],
    "excludeHeadquartersCountries": [
      "string"
    ],
    "excludeIndustries": [
      "string"
    ],
    "excludeJobTitles": [
      "Intern"
    ],
    "headquartersCountries": [
      "string"
    ],
    "industries": [
      "Software Development"
    ],
    "jobFunctions": [
      "Sales & Business Development"
    ],
    "jobTitles": [
      "Head of Sales",
      "VP Sales"
    ],
    "regions": [
      "string"
    ],
    "revenue": [
      "string"
    ],
    "seniorities": [
      "Director"
    ],
    "states": [
      "string"
    ],
    "technologies": [
      "HubSpot"
    ]
  },
  "page": 1,
  "pageSize": 25
}'

Response

{
  "audienceKey": "4f1c0e9a2b7d4c3e8f6a5b1d0c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
  "creditsPerProspect": 1,
  "error": "string",
  "hasMore": true,
  "maxPage": 100,
  "message": "string",
  "page": 1,
  "pageSize": 25,
  "progress": {
    "added": 1000,
    "adds": 2,
    "lastAddAt": "string",
    "nextFrom": 901,
    "runningImportId": 8813
  },
  "results": [
    {
      "company": {
        "industry": "Software Development",
        "logoUrl": "https://api.emailchaser.com/lead-finder/logos/l_2mEuK4r1Xw0pVn8qFh7ZcT5bLd9sYoJ3aGk6",
        "name": "Hopper Ltd",
        "revenueBand": "string",
        "sizeBand": "51 to 200"
      },
      "firstName": "Grace",
      "inWorkspace": false,
      "jobFunction": "Sales & Business Development",
      "lastInitial": "H",
      "location": {
        "city": "Dublin",
        "country": "Ireland",
        "state": "string"
      },
      "ref": "r_Q2x9LmVwZ3JhY2VIb3BwZX",
      "seniority": "Director",
      "title": "Head of Sales"
    }
  ],
  "rowsLeftToday": 1975,
  "searchId": "s_c32d55f8dbd501c71bea43ee",
  "status": "done",
  "total": 2147,
  "totalIsExact": true,
  "totalStatus": "done"
}

Get a Lead Finder search

get https://api.emailchaser.com/r/lead-finder/searches/{id}

Works with a read-only key

Returns a search started with POST /lead-finder/searches. While it is still running the request waits up to about six seconds for it to finish before answering, so calling it again right away is fine. A finished search's results can be read for 10 minutes: after that the search reads as status failed with error expired, and after 15 minutes it is not found. Reading a finished page again within those 10 minutes keeps its people's refs valid for another 60 minutes. Searches belonging to other workspaces are reported as not found.

Parameters

id string required in path
Search ID (searchId)

Responses

200 The search (status running, done or failed) · LeadFinderSearch
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 plan_required: the workspace's plan does not include Lead Finder · LeadFinderError
404 not_found: no such search in this workspace, or it has expired · LeadFinderError
409 provider_unavailable: the contact database is switched off · LeadFinderError
500 internal · LeadFinderError

Fields in the 200 response

audienceKey string
AudienceKey names the filters: the same picks in any order give the same key. Imports from these filters carry it too.
Example: 4f1c0e9a2b7d4c3e8f6a5b1d0c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e
creditsPerProspect integer
Example: 1
error string
Error is set on a failed search: rate_limited, provider_blocked, provider_unavailable (the people database is down or in maintenance; try again later), timeout, invalid_filters, budget_exhausted, expired or internal.
hasMore boolean
Example: true
maxPage integer
Example: 100
message string
page integer
Example: 1
pageSize integer
Example: 25
progress LeadFinderProgress
Progress is what earlier imports from these filters did in the workspace. Left out before the first one.
5 fields inside progress
- added integer
  Added is how many people they added.
  Example: 1000
- adds integer
  Adds is how many imports there were, selected ones included.
  Example: 2
- lastAddAt string
  LastAddAt is when the latest import from these filters started.
- nextFrom integer
  NextFrom is the position in the results (1 is the first person) the next first_n import of these filters starts from.
  Example: 901
- runningImportId integer
  RunningImportID is a first_n import of these filters still running. Another first_n import of the same filters is refused (409 import_running) until it ends.
  Example: 8813
results array of LeadFinderPerson
Results are the people on this page, masked.
9 fields inside results
- company LeadFinderPersonCompany
- firstName string
  Example: Grace
- inWorkspace boolean
  InWorkspace is true for someone Lead Finder added to this workspace whose lead is still there, so adding them again is skipped for free. A person who is a lead from another source shows false; adding them is still skipped and costs nothing.
  Example: false
- jobFunction string
  Example: Sales & Business Development
- lastInitial string
  Example: H
- location LeadFinderPersonLocation
- ref string
  Ref identifies the person for POST /lead-finder/imports. It stays valid for 60 minutes after the page it came on was last shown.
  Example: r_Q2x9LmVwZ3JhY2VIb3BwZX
- seniority string
  Example: Director
- title string
  Example: Head of Sales
rowsLeftToday integer
RowsLeftToday is the account's browsing allowance left this UTC day.
Example: 1975
searchId string
Example: s_c32d55f8dbd501c71bea43ee
status string
Status is running, done or failed.
Example: done
total integer
Total is how many people match; TotalIsExact says whether it is a count or a lower bound, and TotalStatus whether the count has landed (pending, done or failed).
Example: 2147
totalIsExact boolean
Example: true
totalStatus string
Example: done

Request

curl -X GET "https://api.emailchaser.com/r/lead-finder/searches/abc123" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "audienceKey": "4f1c0e9a2b7d4c3e8f6a5b1d0c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
  "creditsPerProspect": 1,
  "error": "string",
  "hasMore": true,
  "maxPage": 100,
  "message": "string",
  "page": 1,
  "pageSize": 25,
  "progress": {
    "added": 1000,
    "adds": 2,
    "lastAddAt": "string",
    "nextFrom": 901,
    "runningImportId": 8813
  },
  "results": [
    {
      "company": {
        "industry": "Software Development",
        "logoUrl": "https://api.emailchaser.com/lead-finder/logos/l_2mEuK4r1Xw0pVn8qFh7ZcT5bLd9sYoJ3aGk6",
        "name": "Hopper Ltd",
        "revenueBand": "string",
        "sizeBand": "51 to 200"
      },
      "firstName": "Grace",
      "inWorkspace": false,
      "jobFunction": "Sales & Business Development",
      "lastInitial": "H",
      "location": {
        "city": "Dublin",
        "country": "Ireland",
        "state": "string"
      },
      "ref": "r_Q2x9LmVwZ3JhY2VIb3BwZX",
      "seniority": "Director",
      "title": "Head of Sales"
    }
  ],
  "rowsLeftToday": 1975,
  "searchId": "s_c32d55f8dbd501c71bea43ee",
  "status": "done",
  "total": 2147,
  "totalIsExact": true,
  "totalStatus": "done"
}

Generated from the Emailchaser API's own OpenAPI definition, so it always matches the running API.

Lead Finder

Get Lead Finder filter values and limits#

Responses

List Lead Finder imports#

Parameters

Responses

Add people to a campaign from the contact database (spends credits and metered verification)#

Request bodyJSON · LeadFinderImportRequest

Responses

Get a Lead Finder import#

Parameters

Responses

Cancel a Lead Finder import#

Parameters

Responses

Search the contact database (free, masked results)#

Request bodyJSON · LeadFinderSearchRequest

Responses

Get a Lead Finder search#

Parameters

Responses

Get Lead Finder filter values and limits

List Lead Finder imports

Add people to a campaign from the contact database (spends credits and metered verification)

Get a Lead Finder import

Cancel a Lead Finder import

Search the contact database (free, masked results)

Get a Lead Finder search