Skip to main content
This guide walks through the most common Leadsforge workflow: find the people who match your ideal customer profile, then get their work emails.
  • Service: Leadsforge API
  • Base URL: https://api.leadsforge.ai/public/v1
  • Cost: search and count are free up to a monthly allowance, then each request costs credits, and every cursor page counts as a search request; enrichment charges your email price for each email found. See Credits.
All examples send your API key in the Authorization header and read it from $LEADSFORGE_API_KEY.
1

Size the audience

Count the people that match your filters before paging through them.
If the response has warnings, some location values match nothing. Use GET /filters/locations/suggestions to find the right spelling. Suggestions are built from people’s locations, so they fit leadLocations; a suggestion can match no company location in companyLocations.
2

Search

Send the same filters with a page size. Each lead has an id: that is the person ID you enrich later.
To get the next page, call POST /search?cursor=... with the cursor from the previous page; the body is then ignored. Stop when a page has no cursor or the API answers 410: once a search has returned 1000 people, the next page answers 410, so refine your filters to reach the people you need. A cursor stays valid for 20 minutes.
3

Start an email enrichment job

Send up to 500 person IDs per job. Add an Idempotency-Key so a retried request does not start a second job, and a clientRequestID of your own to find the job later in the job list (see Asynchronous jobs).
The response is 202 Accepted with the job:
The job reserves your email price for every person whose email your account did not obtain in the last 30 days. At the end it charges only for emails found.
4

Wait for the job

Poll the job until its status is completed or failed.
You can also pass a webhookURL when you start the job to receive each person’s result as soon as it is ready; the job sends no webhook when it ends, so still poll it for its final status. See Asynchronous jobs.
5

Read the results

Page through the results. On succeeded results the email is in payload.email.
A not_found result costs nothing. It can be temporary, so you can try those people again later.

Variations

  • Phone numbers or LinkedIn URLs: the same flow with POST /enrichment/phones (value in payload.phoneNumber) or POST /enrichment/linkedin (value in payload.linkedinURL).
  • People you already know: instead of personIDs, send people with a LinkedIn URL, or first name, last name and a company domain or name. Each entry can carry an externalID that comes back in its result. For emails and phones, a LinkedIn URL we cannot match comes back not_found unless you also send first and last name; LinkedIn enrichment returns not_found for anyone we cannot match.
  • One person at a time: POST /enrichment/email and POST /enrichment/phone return the value in the same response, without a job.