API

The same leads,
from your own code.

No separate plan, no extra charge, no different data. The API and the dashboard are the same code path, so a call can never return more than the same customer sees on screen, and a credit costs exactly what it costs anywhere else.

Getting started

Two minutes

Sign up and take the three free credits.
Create a key under API keys in the dashboard. It is shown once, then stored as a hash we cannot reverse.
Send it as a bearer token on every request.

curl -X POST https://www.fresh-leads.io/api/v1/leads \
  -H "Authorization: Bearer fl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"niche":"dentists","location":"Austin, TX","limit":20}'

Endpoints

Everything you can call

POST/api/v1/leads

Search for leads

Find local businesses matching a trade and an area. Returns leads locked, exactly as the dashboard shows them: who and where, the grade, and whether we verified a way to reach them.

Free. You need at least one credit in your balance to search, but searching never spends one.

Body

niche: string, required. The trade, e.g. "dentists".
location: string, required. Town, city or postcode, e.g. "Austin, TX".
limit: number. Defaults to 50. Up to 250 in an area we search live, and up to 500 in one we hold a full index for, which the response says.
playbook: string. What you sell, which decides how leads are graded: web_design, payments_pos, marketing_seo, booking_software, general_smb.
minRating: number, 1 to 5. Skip businesses rated below this.
minReviews: number. Skip businesses with fewer reviews than this.
webPresence: string: any, has_site, social_only or none.

Returns

{ leads: LockedLead[], notes: string[] }

A locked lead carries no phone, email or address. Those are what a credit buys.
The phone and mailbox are checked live when a lead is opened, not when it was found, so a credit never buys a contact that has since gone dead.
Discovery may be served from our own index, and site audits from a short cache. The response says which, and how old it was.

POST/api/leads/unlock

Open a lead

Spend one credit to reveal a lead in full: verified phone, verified email, address, the grade breakdown and what to pitch.

One credit. Charged once per business, forever. Opening the same lead again is free.

Body

leadId: string, required. The id from a search result.

Returns

{ lead: Lead, creditsLeft: number }

The charge happens inside one database function, so two calls at once cannot spend two credits on the same business.
If the phone and mailbox both turn out to be dead, you are not charged at all.

POST/api/leads/owner

Reveal the owner

The person who runs the business, where we can find one: name, role, and a personal email or profile if it exists.

One credit, once, permanently.

Body

leadId: string, required. Must already be open.

Returns

{ owner: Owner | null, creditsLeft: number }

The lead has to be open first: selling the owner of a business you cannot otherwise see would be selling a fragment.
We find an owner on roughly four in ten businesses, and it varies by trade: a dental practice or a vet usually names the practitioner, a restaurant or a salon usually does not. When we are not confident, we return null rather than a guess.

POST/api/leads/export

Export

Take leads out as a spreadsheet, a JSON payload, a printable call sheet, or under the column names HubSpot and Salesforce expect.

Free for leads you have already opened. One credit each for any that are still locked.

Body

leadIds: string[], 1 to 1000 ids.
format: string: csv, json, pdf, hubspot or salesforce. Defaults to csv.

Returns

A file, with the matching content type.

POST/api/enrich

Enrich your own list

Send a CSV of businesses you already have and get it back with the gaps filled: verified phone and email, the owner where findable, and what we know about their website.

One credit per row we actually enrich. A row we cannot identify comes back untouched and costs nothing.

Body

file: multipart/form-data, up to 500 rows.

Returns

A CSV with our columns appended, plus fl_status on every row.

When something goes wrong

Errors

Response	What it means
`401`	No key, or a key that has been revoked.
`402 subscription_required`	The account needs the yearly plan.
`402 insufficient_credits`	Not enough credits for that call.
`429 rate_limited`	Too many calls. Retry-After says how long to wait.
`400`	The body did not match the shape above.
`500`	Our fault. Safe to retry: every paid action is idempotent. The body carries a short `reference`; quote it and we can find the exact failure in our logs.

Every paid action is idempotent, so retrying a call that failed halfway cannot charge you twice. Opening the same lead again is free whether it is the second attempt or the fiftieth.

Build against it free

Three credits, no card. Enough to search, open a lead and see the exact shape of what comes back before you write a line of integration.

Get a key See pricing