- 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.
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 To get the next page, call
id: that is the person ID you enrich later.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 The response is 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.
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).202 Accepted with the job:4
Wait for the job
Poll the job until its status is You can also pass a
completed or failed.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 A
succeeded results the email is in payload.email.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 inpayload.phoneNumber) orPOST /enrichment/linkedin(value inpayload.linkedinURL). - People you already know: instead of
personIDs, sendpeoplewith a LinkedIn URL, or first name, last name and a company domain or name. Each entry can carry anexternalIDthat comes back in its result. For emails and phones, a LinkedIn URL we cannot match comes backnot_foundunless you also send first and last name; LinkedIn enrichment returnsnot_foundfor anyone we cannot match. - One person at a time:
POST /enrichment/emailandPOST /enrichment/phonereturn the value in the same response, without a job.
