Quickstart

This walk-through uses the HTTP API with cURL, Node.js and Python. To work from an AI agent instead, follow Set up the MCP server.

1. Create an API key

   Open the Leadity API screen on the Leadity app's Connectors page and create an API key. Tick the scopes it needs: every key can read, and placing an order also needs spend. The secret is shown once, so copy it then and keep it somewhere safe.

   export LEADITY_API_KEY="lk_api_..."

2. Make your first request

   Search the niches you can order. A read like this takes no credits.

   cURLNode.jsPython

   curl "https://api.leadity.io/v1/niches?q=roof" \
     -H "Authorization: Bearer $LEADITY_API_KEY"

   The answer groups each niche under its market. The id is what an order names.

   {
     "version": "3f9a1c2b7d4e",
     "groups": [
       {
         "group": "Home Services & Construction",
         "niches": [{ "id": "roofing_contractor", "name": "Roofing Contractor", "multiplier": 1, "findOwner": true }]
       }
     ]
   }

3. Price an order

   estimate_scrape prices an order without placing it. Send the niches, the area and the filters. It takes no lead count: it answers the price of one lead, which prices any count.

   cURL

   curl -X POST "https://api.leadity.io/v1/scrapes/estimate" \
     -H "Authorization: Bearer $LEADITY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "nicheIds": ["roofing_contractor"],
       "selection": { "states": [{ "country": "US", "state": "TX" }] },
       "filters": { "websitePresence": "any", "phoneTypeFilter": "mobile" }
     }'

   A selection names its country and region by code. list_territories lists the countries on sale and each one's regions, and search_areas finds a city or a postal code inside one.

   The answer carries leadRateMilli, the exact price of one lead in thousandths of a credit, and your account's floors: minTargetLeads and minOrderCredits. The price of any number of leads is ceil(leads x leadRateMilli / 1000) credits.

4. Place the order

   create_scrape takes credits, so it needs two things a read does not: an Idempotency-Key header that you keep for this one order, and a maxCredits ceiling worked out from the estimate's rate: 1,000 mobile leads at a leadRateMilli of 1000 cost 1,000 credits. If the price is above the ceiling nothing is charged.

   cURL

   curl -X POST "https://api.leadity.io/v1/scrapes" \
     -H "Authorization: Bearer $LEADITY_API_KEY" \
     -H "Idempotency-Key: tx-roofers-2026-10-04" \
     -H "Content-Type: application/json" \
     -d '{
       "nicheIds": ["roofing_contractor"],
       "selection": { "states": [{ "country": "US", "state": "TX" }] },
       "filters": { "websitePresence": "any", "phoneTypeFilter": "mobile" },
       "targetLeads": 1000,
       "maxCredits": 1000
     }'

   The answer comes back at once, 201, with the scrape's id. The scrape runs from there. If the connection drops before you read it, send the same request with the same key: the retry answers 200 with the same scrape and "replayed": true, and charges nothing again.

5. Wait for it, then download

   Poll get_scrape_status every 30 to 60 seconds until complete is true, then download the leads.

   Node.js

   const headers = { Authorization: `Bearer ${process.env.LEADITY_API_KEY}` };
   const id = "Vb7nW3xQ9k";
   
   for (;;) {
     const status = await (await fetch(`https://api.leadity.io/v1/scrapes/${id}/status`, { headers })).json();
     if (status.complete) break;
     await new Promise((resolve) => setTimeout(resolve, 45_000));
   }
   
   const csv = await (await fetch(`https://api.leadity.io/v1/scrapes/${id}/leads.csv`, { headers })).text();

Next steps