Docs / API Reference / Leads

Leads

Search Google Maps for local business leads and retrieve the results programmatically. A search returns a query ID immediately — poll /progress until it completes, then fetch the leads.

All endpoints require authentication. Each search costs credits from your balance.

Start a Search

POST/api/v1/leads/searchauth

Trigger a new lead search against Google Maps. Returns a query ID immediately — the actual extraction runs asynchronously.

Body parameters

query*
string

Business type or niche to search for. E.g. "Dentists", "Plumbers in Paris".

location
string

City or region to restrict the search. Can also be embedded in query.

locale
string
default en

Language code for results (e.g. fr, de).

country
string (ISO 3166-1)
default US

2-letter country code used to bias results geographically.

resultLimit
20 | 50 | 100 | 500 | 1000 | 2000
default 20

Maximum number of leads to extract. Higher limits cost more credits.

autoEnrich
boolean
default false

If true, automatically run email enrichment after the search completes.

Example response

json
{
  "success": true,
  "data": {
    "query": {
      "id": "cm9search123",
      "query": "Dentists",
      "location": "Austin, TX",
      "status": "PENDING",
      "totalRecords": 0
    },
    "isNew": true
  }
}
curl
curl -X POST https://leadsapi.postorbit.io/api/v1/leads/search \
  -H "Authorization: Bearer $LOCALLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Dentists",
    "location": "Austin, TX",
    "resultLimit": 100
  }'

Poll Search Progress

GET/api/v1/leads/query/:id/progressauth

Check the status of a running search. Poll this until status is COMPLETED or FAILED.

Path parameters

:id*
string

The query ID returned by POST /search.

json
{
  "success": true,
  "data": {
    "status": "PROCESSING",      // PENDING | PROCESSING | COMPLETED | FAILED
    "totalRecords": 47,
    "enrichmentStatus": null,    // null | PENDING | PROCESSING | COMPLETED
    "enrichmentProgress": 0
  }
}
Poll every 2–3 seconds. Most searches complete within 15–60 seconds depending on resultLimit. Stop polling when status is COMPLETED or FAILED.
javascript
// Poll until complete
async function waitForSearch(queryId) {
  const url = `https://leadsapi.postorbit.io/api/v1/leads/query/${queryId}/progress`;
  const headers = { Authorization: `Bearer ${process.env.LOCALLEADS_API_KEY}` };

  while (true) {
    const { data } = await fetch(url, { headers }).then((r) => r.json());
    if (data.status === "COMPLETED") return data;
    if (data.status === "FAILED") throw new Error("Search failed");
    await new Promise((r) => setTimeout(r, 3000)); // wait 3s
  }
}

Get Leads for a Search

GET/api/v1/leads/query/:idauth

Retrieve the paginated list of leads extracted by a completed search.

Path parameters

:id*
string

Query ID.

Query parameters

page
number
default 1

Page number.

limit
number
default 20

Results per page. Max 100.

json
{
  "success": true,
  "data": {
    "query": { "id": "cm9search123", "query": "Dentists", "status": "COMPLETED" },
    "leads": [
      {
        "id": "cm9lead001",
        "name": "Austin Family Dentistry",
        "phone": "+1 512-555-0101",
        "website": "https://austinfamilydentistry.com",
        "address": "123 Main St, Austin, TX 78701",
        "rating": 4.8,
        "reviewCount": 312,
        "email": null,
        "qualityTier": "high"
      }
    ]
  },
  "meta": { "total": 97, "page": 1, "limit": 20 }
}

List All Leads

GET/api/v1/leads/allauth

Retrieve all leads across every search for your organisation with sorting and full-text search.

Query parameters

page
number
default 1

Page number.

limit
number
default 20

Results per page.

sortBy
name | email | phone | createdAt
default createdAt

Field to sort by.

sortOrder
asc | desc
default desc

Sort direction.

search
string

Full-text search across name, email, phone, and address.

qualityTier
high | medium | low

Filter by lead quality tier.

curl
curl "https://leadsapi.postorbit.io/api/v1/leads/all?limit=50&qualityTier=high" \
  -H "Authorization: Bearer $LOCALLEADS_API_KEY"

List Previous Searches

GET/api/v1/leads/prev-searchesauth

List all search queries run by your organisation, newest first.

Query parameters

page
number
default 1

Page number.

limit
number
default 20

Results per page.

json
{
  "success": true,
  "data": [
    {
      "id": "cm9search123",
      "query": "Dentists",
      "location": "Austin, TX",
      "status": "COMPLETED",
      "totalRecords": 97,
      "createdAt": "2026-05-05T10:00:00.000Z"
    }
  ],
  "meta": { "total": 14, "page": 1, "limit": 20 }
}
Rate limit on /search is stricter than other endpoints: 20 searches per minute per user. Batch your requests if automating large-scale searches.
←AuthenticationEnrichment→