Core
Leads
Once a search is completed, page through its extracted leads.
Everything this account owns, however it got here — from a search or from unlocking a row in the shared dataset. Reading your own leads is free; you paid for them once already.
For the leads one particular search produced, use GET /v1/searches/:id/leads instead — that one is scoped to a single search and lives in the Searches namespace.
Query parameters
| Field | Type | Description |
|---|---|---|
| provider | string? | Source maps to keep, comma-separated: google · apple · bing. Omit for all three. |
| limit | number? | Page size (1–500, default 100). |
| cursor | string? | Opaque cursor from the previous response. Keyset paging — pass it back verbatim. |
The response is { "leads": [ lead, ... ], "nextCursor": string | null }.
⚠️ Those three are the only parameters this endpoint takes. The richer filters on GET /v1/businesses — q, country, category, minRating, hasPhone / hasWebsite / hasEmail, emailStatus — are not implemented here yet. Sending one returns 400 rather than quietly ignoring it, so you never get an unfiltered list back believing it was filtered.
One lead, same shape as the list. A lead belonging to someone else is 404, not 403 — a 403 would confirm the id is real.
Everything you own as one file. Unlocked rows have no search behind them, so this is the only way to get those out in bulk. Free — you paid for these rows once already.
| Field | Type | Description |
|---|---|---|
| provider | string? | Source maps to keep, comma-separated. Omit for all three. |
| format | csv | xlsx | json | Output format (default csv). |
| leadIds | string (repeatable) | Optional. ?leadIds=a&leadIds=b to export only those. |
A lead is a copy taken at the moment you acquired it. When the shared record behind it changes, pending-sync says what is newer and sync pulls it in. Free — you are not buying the row again.
The lead object
The same shape everywhere a lead appears, including GET /v1/searches/:id/leads and the export files.
| Field | Type | Description |
|---|---|---|
| id | string | Lead id. |
| provider | string | Map source the lead came from: google · bing · apple. |
| name | string | Business name. |
| fullAddress | string | null | Formatted address. |
| street | string | null | Street. |
| municipality | string | null | City / municipality. |
| categories | string[] | Business categories. |
| latitude | number | null | Latitude. |
| longitude | number | null | Longitude. |
| phone | string | null | Primary phone number. |
| phones | string[] | All phone numbers. |
| website | string | null | Website URL. |
| domain | string | null | Website domain. |
| emails | LeadEmail[] | All discovered emails with BillionVerify status (enrichment, paid plans). |
| socials | Record<string,string> | Social profile URLs (enrichment). |
| technologies | WebsiteTechnology[] | Website technology names, versions, and categories (enrichment). |
| rating | number | null | Average review rating. |
| reviewCount | number | null | Number of reviews. |
| mapsUrl | string | null | Listing URL on the source map. |
| placeId | string | null | Source place id (Google Place ID, Bing ypid, Apple muid). |
Field availability by provider
Every lead uses the same shape, but the source maps expose different fields — missing ones are null / empty. emails and socials are never from the map; they come from website enrichment on all providers.
| Field | Bing | Apple | |
|---|---|---|---|
| name, address, coordinates, phone, website, categories, placeId, mapsUrl | ✓ | ✓ | ✓ |
| street, municipality | ✓ | — | ✓ |
| rating, reviewCount | ✓ | ✓ | — |
| openingHours | by day | single text | — |
| reviewUrl | ✓ | — | — |
| featuredImage | ✓ | ✓ | — |
| priceLevel, claimed | ✓ | — | — |
| emails, socials | enrichment | enrichment | enrichment |
# Everything you own, Apple and Bing only
curl "https://api.mapleads.ai/v1/leads?provider=apple,bing&limit=100" \
-H "Authorization: Bearer mapleads_xxx"
# Next page — pass nextCursor back verbatim
curl "https://api.mapleads.ai/v1/leads?cursor=CURSOR" \
-H "Authorization: Bearer mapleads_xxx"