Skip to main content
Leadsforge API works in two steps. Search finds the people who match your criteria. Enrichment finds contact details for the people you choose: work emails, phone numbers and LinkedIn profile URLs. The two steps are priced differently. Search and count are free up to a monthly allowance, so you can refine your filters before you spend anything; past it, each successful call costs credits. Enrichment consumes credits, and only for values that are actually found. All endpoints live under https://api.leadsforge.ai/public/v1 and use the API key from Settings -> API & MCP in the Leadsforge app, sent as is in the Authorization header. See API endpoints.
1

Search

Describe the people you want with filters and get back matching leads, each with a person ID. Free up to a monthly allowance.
2

Enrich

Pass the person IDs you choose to enrichment and get their work emails, phone numbers or LinkedIn profile URLs. Paid per value found.
A search takes a set of filters and returns matching people page by page. Filters describe the person (job title, seniority, department, location, language, time in role) and their company (name, keywords, industry, size, revenue, funding, technologies, location, domain). Some filters take free text, such as job titles and locations. Others take a fixed set of values, such as seniority or industry; most of those have a free endpoint under /search/filters that lists the accepted values. Each result is a lead with a person ID. That ID is what you pass to enrichment, and it stays the same for the same person across searches. A person removed from our database stops matching, and enrichment skips their ID.

Paging and limits

  • A search returns up to the page size you ask for in limit (1 to 2000 people) and a cursor while more results may exist. Send the cursor to get the next page.
  • A cursor stays valid for 20 minutes after each page.
  • Once a search has returned 1000 people, the next cursor page answers 410; refine your filters to reach the people you need.
  • To size an audience without paging through it, use the count endpoint. It accepts the same filters, without limit, and has its own monthly free allowance.

Enrichment

Enrichment finds one kind of contact detail, called a channel, for the people you choose:
  • Email: the person’s work email.
  • Phone: the person’s phone number.
  • LinkedIn: the person’s LinkedIn profile URL.
You identify people either by person IDs from a search (personIDs), or by the details you already have (people): a LinkedIn profile URL, or first name, last name and a company (a company domain such as salesforge.ai matches better than a company name). If a LinkedIn URL is not a valid profile URL, the entry is matched by name and company when you sent them.

Asynchronous jobs

For lists of people, enrichment runs as a job. You start it with up to 500 people and get a job ID back right away. The job then works through the people in the background. Each person gets their own result: succeeded when a value was found, not_found when none was, or failed when the lookup could not finish. In a job that ended failed, people it had not reached have no result; start a new job for them. Person IDs that match nobody are skipped and not counted in the job’s total, the number of people it processes. With people input, pass your own externalID per person to match results to your records. Duplicate entries (the same LinkedIn URL, the same name and company, or entries that match the same person) get a single result carrying the externalID of the first matching entry, LinkedIn URL entries first, and are counted once in total, so send each person once. Poll the job until its status is final and then page through its results; a webhook URL also delivers each person’s result as soon as it is ready.

Synchronous lookups

For a single person, email and phone can also be looked up synchronously: the result comes back in the same response, with no job and no polling. A synchronous call can take tens of seconds.

Credits

Enrichment charges your account’s price for the channel for each value found. Prices are set per account; read yours from the balance endpoint rather than assuming defaults.
  • A value that is not found costs nothing.
  • A value your account obtained in the last 30 days, through the API or the app, is returned again for free.
  • An asynchronous job reserves credits for the people it has to look up when it starts and, when it finishes, charges only for the values found. The rest of the reservation is released.
Filter value endpoints are free. Search and count are free up to a monthly allowance; see Credits.