Using the API

Downloads

Leads, reviews and validation results as CSV files, and as short-lived links on MCP.

Three operations answer a whole list as one CSV file, and one answers several scrapes in one file:

Operation	File
`download_leads`	Every delivered lead of a scrape, with exactly the columns the order bought.
`download_reviews`	The Google reviews of a scrape that ordered review scraping.
`download_validation`	Every item of a validation run with its verdict.
`export_scrapes`	The leads of several scrapes in one file, `List ID` and `List Name` first.

On the HTTP API

The answer is the file itself, text/csv:

curl "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/leads.csv" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -o leads.csv

A file's columns follow the order, not the data: an order that did not buy owner names has no owner column, and every lead carries its Google Place ID and Google Maps Link. On a scrape that is still running, the file holds what has been delivered so far.

Each file is served under its own name, in the Content-Disposition header and as an MCP link's filename:

Operation	File name
`download_leads`	`leads-<id>.csv`, with the scrape id as written in the path
`download_reviews`	`reviews-<id>.csv`
`export_scrapes`	`leadity-<count>-lists.csv`, with the number of scrapes it holds
`download_validation`	The run's title in lowercase, every run of other characters one hyphen: `Phone validation Oct 4, 14:12` is `phone-validation-oct-4-14-12.csv`

On the MCP server

A list of thousands of leads is not a tool result, so the MCP tool answers a link instead:

{
  "url": "https://api.leadity.io/v1/downloads/dl_8Hq2mZ7xKp4Rt9Wb3Nc6Vy",
  "expiresAt": "2026-10-04T15:12:09.000Z",
  "filename": "leads-Vb7nW3xQ9k.csv"
}

The link needs no key. It lives fifteen minutes, until expiresAt, and opens at most five times, so fetch it soon or hand it to the person you are working for. It also stops working if the key that made it is revoked or the account can no longer download. For a fresh link, call the tool again.

For the leads as data rather than a file, page through list_leads. See Pagination.