Core
Businesses
The shared dataset every account searches. Browsing is free; buying rows into your leads costs one credit each.
Two different things live here, and the difference is the whole billing model: GET tells you what exists and is free, POST /unlock gives you the contents and charges.
Browse the dataset
Returns business name, city, category, rating, whether there is a phone / website / email, and what state each email is in — but never the phone number, the email address or the URL. Those are what unlocking buys.
Query parameters
| Field | Type | Description |
|---|---|---|
| provider | string? | Source maps to keep, comma-separated: google · apple · bing. Omit for all three. |
| q | string? | Free text over name and address. |
| country | string? | ISO country code. |
| locality | string? | City / locality. |
| category | string? | One category. |
| minRating | number? | Minimum rating. |
| hasPhone / hasWebsite / hasEmail | boolean? | Three-state. true keeps only rows that have one, false keeps only rows that do not, omitting the key does not filter at all. |
| emailStatus | string? | Comma-separated: deliverable · role · catch_all · risky · invalid · unverified · verification_failed · none. Any-match. |
| owned | boolean? | Three-state, on whether this account already owns the row. |
| limit | number? | Page size. |
| cursor | string? | Opaque keyset cursor. Use this rather than page for deep paging. |
| page | number? | Page number, 1-based. Mutually exclusive with cursor. |
⚠️ The three-state filters are the point: hasWebsite=true plus hasEmail=false is a real question, and a two-state flag can only answer half of it.
Row identity
Every row carries provider and providerBusinessId — each map's own identifier, passed through unchanged:
| Field | Type | Description |
|---|---|---|
| cid | 727846742557342929 | |
| apple | Place ID | I63802885C8189B2B |
| bing | ypid | YN873x14475615034754698960 |
Bring identifiers you already hold from anywhere — they resolve here directly, no lookup step to translate them. Google rows also carry cid and placeId as convenience aliases.
⚠️ The same business can appear once per map. Those are separate rows with separate identifiers, not duplicates.
Unlock rows into your leads
Buys rows into this account, charging the same credit a search result costs. Synchronous — the leads come back in the response, in full.
| Field | Type | Description |
|---|---|---|
| businesses | { provider, id }[] | Up to 500 per call. References resolving to the same row are charged once. |
Rows you already own come back in alreadyOwned — in the shape you sent — and are not charged, so a double submit or a retry cannot bill twice. If the balance cannot cover the whole batch the call fails with 402 and buys nothing: a partial unlock would leave you unable to tell which rows you got.
# Free: what exists, and which emails will actually deliver
curl "https://api.mapleads.ai/v1/businesses?country=US&locality=Austin&category=dentist&emailStatus=deliverable" \
-H "Authorization: Bearer mapleads_xxx"
# Paid: buy two rows, using identifiers you already had
curl https://api.mapleads.ai/v1/businesses/unlock \
-X POST \
-H "Authorization: Bearer mapleads_xxx" \
-H "Content-Type: application/json" \
-d '{"businesses":[
{"provider":"google","id":"727846742557342929"},
{"provider":"apple","id":"I63802885C8189B2B"}
]}'