Lead Finder

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

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.

post/lead-finder/imports

Request

  • Base URL: https://api.emailchaser.com/r
  • URL: https://api.emailchaser.com/r/lead-finder/imports
  • Auth: HTTP bearer

Request body

campaignIdinteger

CampaignID is the campaign the people are added to.

countinteger

Count is how many people to add, for mode first_n: 1 to 5,000.

fromStartboolean

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.

mode'selected' | 'first_n'

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).

refsstring[]

Refs are result refs from searches, for mode selected: 1 to 1,000.

verifyEmailsboolean

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 request

{
  "campaignId": 123,
  "count": 200,
  "filters": {
    "cities": [
      "Dublin"
    ],
    "companySizes": [
      "51 to 200"
    ],
    "countries": [
      "Ireland"
    ],
    "domains": [
      "acme.com"
    ],
    "excludeJobTitles": [
      "Intern"
    ],
    "industries": [
      "Software Development"
    ],
    "jobFunctions": [
      "Sales & Business Development"
    ],
    "jobTitles": [
      "Head of Sales",
      "VP Sales"
    ],
    "seniorities": [
      "Director"
    ],
    "technologies": [
      "HubSpot"
    ]
  },
  "mode": "selected",
  "refs": [
    "r_Q2x9LmVwZ3JhY2VIb3BwZX"
  ],
  "verifyEmails": true
}

Response

Import started

audienceKeystring

AudienceKey names the import's filters, as on a search.

availableinteger

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.

creditsPerProspectinteger
estimatedCreditsinteger

EstimatedCredits is Requested x CreditsPerProspect, the most this import can cost in credits. Skipped people cost no credits; metered verification is billed separately.

expiredinteger

Expired counts refs that were no longer stored and were dropped.

importIdinteger
requestedinteger

Requested is how many people the import will try to add.

startsAtinteger

StartsAt is the position in the results a first_n import starts from: 1 is the first person. Left out for a selected import.

statusstring

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.