API reference
Google Maps Scraper API
The MapsDaddy Google Maps scraper API does everything the dashboard does, from your own code: scrape Google Maps by category and location, export ready-made businesses from the Local Business Database, and enrich your lists with websites, emails, social links and decision makers. It's a simple JSON REST API that uses the same credits, prices and lists as your dashboard.
https://api.mapsdaddy.com/api/v1Get your API key
Create a key in your dashboard.
Quickstart
Get your first list in 2 minutes.
MCP Server
Let an AI assistant do it for you.
How it works
- 1
Find businesses
Scrape Google Maps with categories and locations, or export from the Local Business Database with filters. Either way you get a list.
- 2
Track it
Poll the order or export, or get a webhook. Most scrapes finish in seconds, and big exports within a minute or two.
- 3
Enrich it
Run Enrich Contacts on the list to add websites, emails, social links or decision makers. A dry run shows the cost first.
- 4
Use it
Read the rows as JSON, or download the list as CSV or Excel with every enrichment result included.
Quickstart
Three requests take you from a fresh API key to a finished list. From there you can enrich it and download it with the Lists and Enrich Contacts endpoints.
Check your key and balance
Store your key in an environment variable, then call /me. A 200 response means you're connected.
curl "https://api.mapsdaddy.com/api/v1/me" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"Scrape Google Maps
Send your business categories and locations to the Google Maps Scraper. Save the order_id from the response: once done, it's also your list_id.
curl -X POST "https://api.mapsdaddy.com/api/v1/google-maps-scraper" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: scrape-2026-11-10-001" \
-d '{
"categories": [
"Dentist",
"Orthodontist"
],
"locations": [
"Austin, Texas, United States",
"Cedar Park, Texas, United States"
],
"results_file_name": "dentists-austin",
"callback_url": "https://example.com/webhooks/mapsdaddy"
}'Check status and download
Poll the order until status is completed (usually seconds), then download the file from download_url. Or skip polling with a callback_url.
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"Authentication
Every request needs your API key in the Authorization header as a bearer token. Create, view or regenerate your key on the API Key page.
Authorization: Bearer YOUR_API_KEYexport MAPSDADDY_API_KEY="md_live_..."Credits & pricing
Everything is priced in credits, the same as in your dashboard. Credits are pay as you go: buy a package or a custom amount whenever you need them, and they never expire. The Google Maps Scraper is a flat price per search. The Local Business Database charges each business once per account, so businesses you exported before are free. Enrichment holds credits when it starts and refunds every row with no result. See the Pricing page for packages.
| Service | Endpoint | Credits |
|---|---|---|
| Google Maps Scraper | /google-maps-scraper | 10 per search |
| Local Business Database | /business-database/exports | 0.5 per business |
| Find Contacts Email (Waterfall) | /lists/{list_id}/enrichments | 5 per result found |
| personal_email | /lists/{list_id}/enrichments | 10 per result found |
| Find Contact Phone Number (Waterfall) | /lists/{list_id}/enrichments | 20 per result found |
| Verify Emails | /lists/{list_id}/enrichments | 0.5 per row checked |
| Find Company Website | /lists/{list_id}/enrichments | 2 per result found |
| Find Business Email | /lists/{list_id}/enrichments | 5 per result found |
| Find Company Social Media | /lists/{list_id}/enrichments | 3 per result found |
| Find Decision Makers | /lists/{list_id}/enrichments | 20 per result found |
Live values are always available from GET /pricing.
Errors
Errors use standard HTTP status codes and always return the same JSON shape, with a stable code you can branch on and a readable message.
Status codes
- 400Invalid request: the message names the field
- 401Missing, invalid or revoked API key
- 402Not enough credits
- 403Account suspended, or the Local Business Database is switched off
- 404Order, list or export not found
- 409File or list not ready yet
- 410File expired, or an endpoint for a tool that's no longer offered
- 429Rate limit exceeded
- 500Something went wrong on our side
{
"error": {
"code": "insufficient_credits",
"message": "Insufficient credits for this order."
}
}Rate limits
Each API key can make 60 requests per minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get a 429; wait a few seconds and retry.
Idempotency
Network hiccups happen. Add an Idempotency-Key header (8–100 characters, unique per request) when you scrape, export or enrich. If you retry with the same key, you get the original order, export or run back instead of being charged twice.
Google Maps Scraper
Google Maps Scraper
https://api.mapsdaddy.com/api/v1/google-maps-scraperScrape Google Maps live: every business in each search, with name, website, address, phone number, category, rating, review count, opening hours and the Google Maps link. Send business categories and locations (every category in every location is one search), or one search URL. The result is a new list you can read, enrich and download.
Body parameters
- categoriesstring[]optional
Business categories, for example Dentist. Up to 500. Send with locations, instead of search_url.
- locationsstring[]optional
Places to search, for example Austin, Texas, United States. Up to 2,000. Send with categories, instead of search_url.
- search_urlstringoptional
A Google Maps search URL (https://www.google.com/maps/search/dentists+in+austin+tx/@30.2672,-97.7431,12z), instead of categories and locations. maps.app.goo.gl share links work too.
- per_searchnumberoptional
The most businesses to take from each search. Leave it out for as many as Google shows (up to about 200 a search).
- deep_searchbooleanoptional
true: a deep search. After the normal results, MapsDaddy sweeps the area in smaller map views to get more than the ~120 businesses one Google Maps search shows, where more exist. Priced per deep search (credits_per_deep_search in GET /pricing) instead of per search.
- results_file_namestringrequired
Name for the order, the new list and its file (1–120 characters).
- notestringoptional
Optional note kept with the order (max 1,000 characters).
- callback_urlstringoptional
Public HTTPS URL notified when the order moves to processing, delivered or cancelled.
- output_formatstringoptional
File format of the delivery. Defaults to csv.
csvxlsx
Headers
- Authorizationstringrequired
Bearer YOUR_API_KEY
- Content-Typestringrequired
application/json
- Idempotency-Keystringoptional
Makes retries safe: sending the same key again returns the original result instead of charging twice.
Returns
- messagestring
Human-readable confirmation for the accepted order.
- order_idstring
Unique order ID. Once it's done, it's also the list_id of the new list.
- order_numbernumber
Short order number shown in your dashboard.
- servicestring
Always people for the Google Maps Scraper.
- statusstring
Current status. New orders start as pending or queued.
pendingqueuedprocessingcompletedcancelled - requested_countnumber
Always 0 on the Google Maps Scraper, which has a flat price and no quantity.
- credits_deductednumber
Credits deducted from your balance for this order.
- new_balancenumber
Your credit balance after the deduction.
- status_urlstring
Authenticated endpoint to poll for status and result details.
- download_urlstring | null
Public link to the result file once the order is completed (no API key needed, valid until the file expires); null until then.
- callback_urlstring | null
Webhook URL accepted for this order, or null when none was supplied.
- callback_signing_secretstring | null
Returned once when callback_url is supplied. Store it to verify webhook signatures.
Status codes
- 201Order created
- 400Invalid request
- 401API key missing or invalid
- 402Insufficient credits
- 403Account suspended
- 429Rate limit exceeded
Good to know
- Send either search_url, or both categories and locations, not both.
- Costs a flat 10 credits per search. Searches are categories × locations, and a search_url is one search. This example is 2 × 2 = 4 searches.
- Credits are deducted when the order is accepted. The price is the same however many businesses come back. If the order is cancelled, its credits are refunded.
- Orders start straight away and run one after another with other customers' orders. A single search usually finishes in under 10 seconds, and 100,000 businesses in about a minute or two.
- Poll status_url (or use callback_url). Once completed, the order_id is also the list_id: read it with Get List Rows, or add emails and decision makers with Enrich a List.
curl -X POST "https://api.mapsdaddy.com/api/v1/google-maps-scraper" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: scrape-2026-11-10-001" \
-d '{
"categories": [
"Dentist",
"Orthodontist"
],
"locations": [
"Austin, Texas, United States",
"Cedar Park, Texas, United States"
],
"results_file_name": "dentists-austin",
"callback_url": "https://example.com/webhooks/mapsdaddy"
}'{
"message": "Order created successfully",
"order_id": "ord_8f2c41d9a7b34e01",
"order_number": 1042,
"service": "people",
"status": "queued",
"requested_count": 0,
"credits_deducted": 40,
"new_balance": 12360,
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
"download_url": null,
"callback_url": "https://example.com/webhooks/mapsdaddy",
"callback_signing_secret": "whsec_3b9f0c2e7d41a8b6c5e0f19d2a7c4b81e6f3d905"
}Local Business Database
Search the Local Business Database
https://api.mapsdaddy.com/api/v1/business-database/searchSearch businesses we already collected from Google Maps, with the same filters as the app. Free: it returns how many match and the first 50, so you can check a search before exporting it.
Body parameters
- filtersobjectoptional
Which businesses. Every filter is optional: leave one out to match everything. Send {} for the whole database.
- filters.searchstringoptional
Text in the business name or website.
- filters.categoriesstring[]optional
Business types, like Dentist or Plumber. Any of them matches, and part of a word works (dent finds Dentist and Dental clinic).
- filters.locationsstring[]optional
Cities, states or countries, like Austin, Texas or Canada. Any of them matches.
- filters.zip_codesstring[]optional
ZIP or postal codes.
- filters.has_websitebooleanoptional
true: only businesses with a website. false: only without one.
- filters.has_phonebooleanoptional
true: only businesses with a phone number. false: only without one.
- filters.has_opening_hoursbooleanoptional
true: only businesses that list opening hours.
- filters.min_ratingnumberoptional
Lowest Google rating, 0 to 5.
- filters.min_reviewsnumberoptional
Fewest Google reviews.
- filters.max_reviewsnumberoptional
Most Google reviews.
- filters.open_onstring[]optional
Days the business must be open.
MonTueWedThuFriSatSun - filters.open_24_hoursbooleanoptional
true: only businesses open 24 hours.
- filters.include_listsstring[]optional
Only businesses in these lists, by list_id or File ID (Exp_12).
- filters.exclude_listsstring[]optional
Leave out businesses in these lists, for example ones you already exported.
- filters.sortstringoptional
Order of the results. todays_picks (the default) is a shuffled order that changes every day.
todays_picksrating_descrating_ascreviews_descreviews_ascname_ascname_desc
Headers
- Authorizationstringrequired
Bearer YOUR_API_KEY
- Content-Typestringrequired
application/json
Returns
- totalnumber
How many businesses match. Counting stops at 100,000.
- total_is_cappedboolean
true when more than 100,000 match.
- businessesarray
The first 50 matches (fields below).
- businesses[].business_idstring
The business's MapsDaddy ID, like MDfb5ngckc9.
- businesses[].namestring
Business name.
- businesses[].category / categoriesstring / string[]
Main category, and every category Google lists.
- businesses[].address, city, state, countrystring | null
Where the business is.
- businesses[].phonestring | null
Phone number, always in full.
- businesses[].websitestring | null
Website. Partly hidden (the first letters, then dots) until your account has exported the business.
- businesses[].website_hiddenboolean
true while the website is partly hidden.
- businesses[].rating / review_countnumber | null
Google rating and number of reviews.
- businesses[].opening_hoursstring | null
Like Mon: 8 AM–5 PM; Tue: 8 AM–5 PM.
- businesses[].google_maps_urlstring | null
The Google Maps link, once the business is exported.
- businesses[].already_paidboolean
true when your account exported this business before: exporting it again is free.
- credits_per_businessnumber
What each business costs to export.
Status codes
- 200Success
- 400Invalid filter: the message names it
- 403Local Business Database switched off
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Nothing is charged for searching.
- To get every match, with full websites and Google Maps links, export it.
curl -X POST "https://api.mapsdaddy.com/api/v1/business-database/search" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filters": {
"categories": [
"Dentist"
],
"locations": [
"Austin, Texas, United States"
],
"has_website": true,
"min_rating": 4.5
}
}'{
"total": 1284,
"total_is_capped": false,
"businesses": [
{
"business_id": "MDfb5ngckc9",
"name": "Lone Star Smiles",
"category": "Dentist",
"categories": [
"Dentist",
"Cosmetic dentist"
],
"address": "1200 S Lamar Blvd, Austin, TX 78704, United States",
"city": "Austin",
"state": "Texas",
"country": "United States",
"phone": "+1 512-555-0142",
"website": "lon••••••••",
"website_hidden": true,
"rating": 4.8,
"review_count": 312,
"opening_hours": "Mon: 8 AM–5 PM; Tue: 8 AM–5 PM; Wed: 8 AM–5 PM; Thu: 8 AM–5 PM; Fri: 8 AM–3 PM; Sat: Closed; Sun: Closed",
"google_maps_url": null,
"already_paid": false
},
{
"business_id": "MD2k8d0qz7a",
"name": "Barton Creek Dental",
"category": "Dentist",
"categories": [
"Dentist",
"Cosmetic dentist"
],
"address": "2700 Bee Caves Rd, Austin, TX 78704, United States",
"city": "Austin",
"state": "Texas",
"country": "United States",
"phone": "+1 512-555-0187",
"website": "https://bartoncreekdental.example.com/",
"website_hidden": false,
"rating": 4.6,
"review_count": 198,
"opening_hours": "Mon: 8 AM–5 PM; Tue: 8 AM–5 PM; Wed: 8 AM–5 PM; Thu: 8 AM–5 PM; Fri: 8 AM–3 PM; Sat: Closed; Sun: Closed",
"google_maps_url": "https://www.google.com/maps?cid=3259798637515848100",
"already_paid": true
}
],
"credits_per_business": 0.5,
"note": "Searches are free and show the first 50 matches. Export to get every match, with full websites."
}Local Business Database
Price an Export
https://api.mapsdaddy.com/api/v1/business-database/quoteWhat exporting these businesses would cost, before anything is charged. Businesses your account exported before are free and counted in already_paid.
Body parameters
- filtersobjectoptional
Which businesses. Every filter is optional: leave one out to match everything. Send {} for the whole database.
- filters.searchstringoptional
Text in the business name or website.
- filters.categoriesstring[]optional
Business types, like Dentist or Plumber. Any of them matches, and part of a word works (dent finds Dentist and Dental clinic).
- filters.locationsstring[]optional
Cities, states or countries, like Austin, Texas or Canada. Any of them matches.
- filters.zip_codesstring[]optional
ZIP or postal codes.
- filters.has_websitebooleanoptional
true: only businesses with a website. false: only without one.
- filters.has_phonebooleanoptional
true: only businesses with a phone number. false: only without one.
- filters.has_opening_hoursbooleanoptional
true: only businesses that list opening hours.
- filters.min_ratingnumberoptional
Lowest Google rating, 0 to 5.
- filters.min_reviewsnumberoptional
Fewest Google reviews.
- filters.max_reviewsnumberoptional
Most Google reviews.
- filters.open_onstring[]optional
Days the business must be open.
MonTueWedThuFriSatSun - filters.open_24_hoursbooleanoptional
true: only businesses open 24 hours.
- filters.include_listsstring[]optional
Only businesses in these lists, by list_id or File ID (Exp_12).
- filters.exclude_listsstring[]optional
Leave out businesses in these lists, for example ones you already exported.
- filters.sortstringoptional
Order of the results. todays_picks (the default) is a shuffled order that changes every day.
todays_picksrating_descrating_ascreviews_descreviews_ascname_ascname_desc - limitnumberoptional
Only the first N matches. Up to 100,000 per export.
Headers
- Authorizationstringrequired
Bearer YOUR_API_KEY
- Content-Typestringrequired
application/json
Returns
- businessesnumber
How many the export would have.
- already_paidnumber
Of those, how many your account exported before (free).
- new_businessesnumber
How many are charged.
- creditsnumber
What the export would cost: new_businesses × credits_per_business, rounded up.
- credits_per_businessnumber
Price per business.
- balancenumber
Your credit balance now.
- max_per_exportnumber
The most businesses one export can have.
Status codes
- 200Success
- 400Invalid filter or limit
- 403Local Business Database switched off
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Send the same filters and limit to Export Businesses to get exactly this selection.
curl -X POST "https://api.mapsdaddy.com/api/v1/business-database/quote" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filters": {
"categories": [
"Dentist"
],
"locations": [
"Austin, Texas, United States"
],
"has_website": true,
"min_rating": 4.5
},
"limit": 1000
}'{
"businesses": 1000,
"already_paid": 120,
"new_businesses": 880,
"credits": 440,
"credits_per_business": 0.5,
"balance": 12400,
"max_per_export": 100000
}Local Business Database
Export Businesses
https://api.mapsdaddy.com/api/v1/business-database/exportsExport the businesses matching the filters as a new list, with full websites and every column. Each business is charged once per account: ones you exported before are free. The file is built in the background.
Body parameters
- filtersobjectoptional
Which businesses. Every filter is optional: leave one out to match everything. Send {} for the whole database.
- filters.searchstringoptional
Text in the business name or website.
- filters.categoriesstring[]optional
Business types, like Dentist or Plumber. Any of them matches, and part of a word works (dent finds Dentist and Dental clinic).
- filters.locationsstring[]optional
Cities, states or countries, like Austin, Texas or Canada. Any of them matches.
- filters.zip_codesstring[]optional
ZIP or postal codes.
- filters.has_websitebooleanoptional
true: only businesses with a website. false: only without one.
- filters.has_phonebooleanoptional
true: only businesses with a phone number. false: only without one.
- filters.has_opening_hoursbooleanoptional
true: only businesses that list opening hours.
- filters.min_ratingnumberoptional
Lowest Google rating, 0 to 5.
- filters.min_reviewsnumberoptional
Fewest Google reviews.
- filters.max_reviewsnumberoptional
Most Google reviews.
- filters.open_onstring[]optional
Days the business must be open.
MonTueWedThuFriSatSun - filters.open_24_hoursbooleanoptional
true: only businesses open 24 hours.
- filters.include_listsstring[]optional
Only businesses in these lists, by list_id or File ID (Exp_12).
- filters.exclude_listsstring[]optional
Leave out businesses in these lists, for example ones you already exported.
- filters.sortstringoptional
Order of the results. todays_picks (the default) is a shuffled order that changes every day.
todays_picksrating_descrating_ascreviews_descreviews_ascname_ascname_desc - limitnumberoptional
Only the first N matches. Up to 100,000 per export.
- results_file_namestringrequired
Name for the new list and its file (1–120 characters).
- output_formatstringoptional
File format. Defaults to csv.
csvxlsx
Headers
- Authorizationstringrequired
Bearer YOUR_API_KEY
- Content-Typestringrequired
application/json
- Idempotency-Keystringoptional
Makes retries safe: sending the same key again returns the original result instead of charging twice.
Returns
- export_idnumber
Check progress with Get an Export.
- statusstring
processing while the file is built (100,000 businesses take about a minute).
processingreadyfailed - businessesnumber
Businesses in the export.
- credits_deductednumber
Credits charged (only for businesses your account hadn't paid for).
- list_id / file_idstring | null
The new list, once ready.
- download_urlstring | null
Public link to the file, once ready.
- status_urlstring
Get an Export for this export.
- new_balancenumber
Your balance after the charge.
Status codes
- 201Export started
- 200Same Idempotency-Key: the original export
- 400Invalid request, or no businesses match
- 402Insufficient credits
- 403Local Business Database switched off
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Costs 0.5 credits per business you haven't exported before. Use Price an Export first to see the exact cost.
- Credits are charged when the export starts. Send an Idempotency-Key so a retry returns the same export instead of charging again.
- The new list works like a scraped one: read its rows, enrich it and download it from the Lists endpoints.
curl -X POST "https://api.mapsdaddy.com/api/v1/business-database/exports" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: export-2026-11-10-001" \
-d '{
"filters": {
"categories": [
"Dentist"
],
"locations": [
"Austin, Texas, United States"
],
"has_website": true,
"min_rating": 4.5
},
"limit": 1000,
"results_file_name": "Austin dentists"
}'{
"export_id": 318,
"results_file_name": "Austin dentists",
"output_format": "csv",
"businesses": 1000,
"credits_deducted": 440,
"status_url": "https://api.mapsdaddy.com/api/v1/business-database/exports/318",
"error": null,
"created_at": "2026-11-10T10:02:17.000Z",
"status": "processing",
"list_id": null,
"file_id": null,
"download_url": null,
"finished_at": null,
"new_balance": 11960
}Local Business Database
Get an Export
https://api.mapsdaddy.com/api/v1/business-database/exports/{export_id}An export's progress. Once status is ready, list_id is the new list and download_url links to the file.
Path parameters
- export_idnumberrequired
The export_id from Export Businesses.
Status codes
- 200Success
- 404Export not found
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Same fields as Export Businesses. Checking every few seconds is fine: most exports are ready within a minute.
curl "https://api.mapsdaddy.com/api/v1/business-database/exports/318" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"export_id": 318,
"results_file_name": "Austin dentists",
"output_format": "csv",
"businesses": 1000,
"credits_deducted": 440,
"status_url": "https://api.mapsdaddy.com/api/v1/business-database/exports/318",
"error": null,
"created_at": "2026-11-10T10:02:17.000Z",
"status": "ready",
"list_id": "ord_c41d9a7b34e01f8a",
"file_id": "Exp_14",
"download_url": "https://api.mapsdaddy.com/api/orders/ord_c41d9a7b34e01f8a/download?file=0&t=Qm4pXw2Ks9",
"finished_at": "2026-11-10T10:02:21.000Z"
}Lists
List Lists
https://api.mapsdaddy.com/api/v1/listsYour lists, newest first: every Google Maps scrape and Local Business Database export, with the File ID you see in Lists & Exports.
Query parameters
- statusstringoptional
Only lists with this status.
pendingqueuedprocessingcompletedcancelled - limitnumberoptional
Page size, 1–100. Defaults to 20.
- offsetnumberoptional
How many to skip. Defaults to 0.
Returns
- data[].list_idstring
Use it with the other Lists and Enrich Contacts endpoints. The File ID (Exp_14) works too.
- data[].file_idstring
The File ID shown in Lists & Exports.
- data[].sourcestring
Where the list came from.
google_maps_scraperbusiness_database - data[].businessesnumber | null
Businesses in the list, once completed.
- data[].searchesnumber | null
Searches in a scrape.
- data[].rows_url / download_url / enrichments_urlstring
Links to read, download and enrich the list.
- data[].expires_atstring | null
When the file stops being kept.
- total / has_morenumber / boolean
For paging with limit and offset.
Status codes
- 200Success
- 400Invalid status, limit or offset
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Enrichment runs aren't separate lists: their results are added to the list they ran on.
curl "https://api.mapsdaddy.com/api/v1/lists?limit=20" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"data": [
{
"list_id": "ord_c41d9a7b34e01f8a",
"file_id": "Exp_14",
"name": "Austin dentists",
"source": "business_database",
"status": "completed",
"businesses": 1000,
"searches": null,
"created_at": "2026-11-10T09:24:11.000Z",
"rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/rows",
"download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/download",
"enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/enrichments",
"expires_at": "2027-05-09T09:24:52.000Z"
},
{
"list_id": "ord_8f2c41d9a7b34e01",
"file_id": "Exp_13",
"name": "dentists-austin",
"source": "google_maps_scraper",
"status": "completed",
"businesses": 684,
"searches": 4,
"created_at": "2026-11-10T09:24:11.000Z",
"rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/rows",
"download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/download",
"enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/enrichments",
"expires_at": "2027-05-09T09:24:52.000Z"
}
],
"total": 14,
"limit": 20,
"offset": 0,
"has_more": false
}Lists
Get a List
https://api.mapsdaddy.com/api/v1/lists/{list_id}One list, by its list_id or File ID.
Path parameters
- list_idstringrequired
The list_id (ord_...) or File ID (Exp_14).
Status codes
- 200Success
- 404List not found
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Same fields as one item of List Lists.
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"list_id": "ord_c41d9a7b34e01f8a",
"file_id": "Exp_14",
"name": "Austin dentists",
"source": "business_database",
"status": "completed",
"businesses": 1000,
"searches": null,
"created_at": "2026-11-10T09:24:11.000Z",
"rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/rows",
"download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/download",
"enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/enrichments",
"expires_at": "2027-05-09T09:24:52.000Z"
}Lists
Get List Rows
https://api.mapsdaddy.com/api/v1/lists/{list_id}/rowsOne page of a finished list as JSON: 50 rows, each an object keyed by column name, with any enrichment results added as columns.
Query parameters
- list_idstringrequired
In the path: the list_id or File ID.
- pagenumberoptional
Page number, from 1. Defaults to 1.
Returns
- columnsstring[]
Column names in order. A repeated name gets (2), (3).
- rowsobject[]
Up to 50 rows, each keyed by column name. Values are text.
- total / has_morenumber / boolean
Rows in the list, and whether there's another page.
Status codes
- 200Success
- 404List not found
- 409List not ready yet
- 410File expired
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- For the whole list at once, use Download a List.
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/rows?page=1" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"list_id": "ord_c41d9a7b34e01f8a",
"page": 1,
"page_size": 50,
"total": 1000,
"has_more": true,
"columns": [
"Business ID",
"Business Name",
"Website",
"Phone Number",
"Category",
"Rating",
"Rating Count",
"Address",
"Business Email"
],
"rows": [
{
"Business ID": "MDfb5ngckc9",
"Business Name": "Lone Star Smiles",
"Website": "https://lonestarsmiles.example.com/",
"Phone Number": "+1 512-555-0142",
"Category": "Dentist",
"Rating": "4.8",
"Rating Count": "312",
"Address": "1200 S Lamar Blvd, Austin, TX 78704, United States",
"Business Email": "hello@lonestarsmiles.example.com"
}
]
}Lists
Download a List
https://api.mapsdaddy.com/api/v1/lists/{list_id}/downloadThe whole list as CSV or Excel, with every enrichment result added as columns.
Query parameters
- list_idstringrequired
In the path: the list_id or File ID.
- formatstringoptional
Defaults to csv.
csvxlsx
Status codes
- 200The file
- 404List not found
- 409List not ready yet
- 410File expired
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Unlike download_url on an order (the file as delivered), this includes enrichment results.
- Files are kept for six months after delivery.
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/download?format=csv" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-L -o "austin-dentists.csv"Business ID,Business Name,Website,Phone Number,Category,Rating,Rating Count,Business Email
MDfb5ngckc9,Lone Star Smiles,https://lonestarsmiles.example.com/,+1 512-555-0142,Dentist,4.8,312,hello@lonestarsmiles.example.com
MD2k8d0qz7a,Barton Creek Dental,https://bartoncreekdental.example.com/,+1 512-555-0187,Dentist,4.6,198,Enrich Contacts
List Enrichment Services
https://api.mapsdaddy.com/api/v1/enrichmentsThe Enrich Contacts services: what each costs, the list columns it reads and the columns it adds.
Parameters
No parameters. Just send the Authorization header.
Returns
- services[].servicestring
The key to send to Enrich a List.
website_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier - services[].credits_per_resultnumber
Credits per result found (or per row checked, for Verify Emails).
- services[].charged_forstring
What you pay for.
results_foundrows_checked - services[].columnsarray
The list columns the service reads. They're matched to your list automatically.
- services[].adds_columnsstring[]
The columns it adds to your list.
- services[].optionsobject
Find Decision Makers only: its settings.
Status codes
- 200Success
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- The response lists every service that's switched on (this example shows two).
curl "https://api.mapsdaddy.com/api/v1/enrichments" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"services": [
{
"service": "biz_email_finder",
"name": "Find Business Email",
"description": "Find public business emails from a website",
"credits_per_result": 5,
"charged_for": "results_found",
"columns": [
{
"key": "company_domain",
"label": "Website / Domain",
"required": true
}
],
"adds_columns": [
"Email"
],
"enabled": true
},
{
"service": "contact_enrichment",
"name": "Find Decision Makers",
"description": "Find decision makers and their contact details",
"credits_per_result": 20,
"charged_for": "results_found",
"columns": [
{
"key": "company_domain",
"label": "Company Domain",
"required": true
}
],
"adds_columns": [
"Full Name",
"First Name",
"Last Name",
"Job Title",
"LinkedIn URL",
"Email"
],
"enabled": true,
"options": {
"job_titles": "Optional. Job titles to look for, up to 100 (for example Owner, CEO, Marketing Manager).",
"countries": "Optional. Where the people are based, up to 100 countries.",
"max_people_per_company": "Optional. 1 to 50, default 5. Each person found is one result."
}
}
]
}Enrich Contacts
Enrich a List
https://api.mapsdaddy.com/api/v1/lists/{list_id}/enrichmentsRun an Enrich Contacts service on a finished list: websites, business emails, social links, decision makers and more. Send dry_run first to see how many rows would run and the most it could cost, without charging anything.
Body parameters
- list_idstringrequired
In the path: the list_id or File ID.
- servicestringrequired
Which service. See List Enrichment Services.
website_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier - dry_runbooleanoptional
true: only return the rows that would run and the most it could cost. Nothing is charged.
- limitnumberoptional
Run only the first N rows that can run.
- columnsobjectoptional
Optional. Which list column each input reads, like {"company_domain": "Website"}. Leave it out to match them automatically.
- options.job_titlesstring[]optional
Find Decision Makers: job titles to look for.
- options.countriesstring[]optional
Find Decision Makers: where the people are based.
- options.max_people_per_companynumberoptional
Find Decision Makers: 1 to 50, default 5.
Headers
- Authorizationstringrequired
Bearer YOUR_API_KEY
- Content-Typestringrequired
application/json
- Idempotency-Keystringoptional
Makes retries safe: sending the same key again returns the original result instead of charging twice.
Returns
- enrichment_idstring
The new column set on the list. See List a List's Enrichments.
- run.run_idstring
The run, an order: check it with Get Order Status.
- run.rowsnumber
Rows sent to the service.
- run.creditsobject
held is set aside now; rows with no result are refunded when the run finishes.
- dry run: rows, most_creditsnumber
With dry_run: how many rows would run, and the most it could cost.
Status codes
- 201Enrichment started
- 200Dry run, or the same Idempotency-Key again
- 400Unknown service, a column the list doesn't have, or no rows to run
- 402Insufficient credits
- 404List not found
- 409List not ready yet
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Example: Find Business Email costs 5 credits per email found. A dry run returns { "rows": 500, "most_credits": 2,500, ... } and charges nothing.
- Rows already enriched by the same service aren't run again, so you never pay twice for a row.
- Credits are held when the run starts; anything not found goes back to your balance. Send an Idempotency-Key so a retry can't start a second run.
- Results appear in Get List Rows and Download a List as the run finishes.
curl -X POST "https://api.mapsdaddy.com/api/v1/lists/Exp_14/enrichments" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: enrich-2026-11-10-001" \
-d '{
"service": "biz_email_finder",
"limit": 500
}'{
"enrichment_id": "col_5d7a1e93c2b84f60",
"run": {
"run_id": "ord_e01f8a2c41d9a7b3",
"service": "biz_email_finder",
"status": "pending",
"rows": 500,
"credits": {
"deducted": 2500,
"held": 2500,
"refunded": 0,
"charged": 0
},
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_e01f8a2c41d9a7b3"
},
"new_balance": 9900
}Enrich Contacts
List a List's Enrichments
https://api.mapsdaddy.com/api/v1/lists/{list_id}/enrichmentsThe enrichments added to a list, with progress and each run's credits.
Path parameters
- list_idstringrequired
The list_id or File ID.
Returns
- data[].progressobject | null
done and total rows.
- data[].runs[].creditsobject
charged is the final cost; refunded went back for rows with no result.
Status codes
- 200Success
- 404List not found
- 401API key missing or invalid
- 429Rate limit exceeded
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/enrichments" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"list_id": "ord_c41d9a7b34e01f8a",
"data": [
{
"enrichment_id": "col_5d7a1e93c2b84f60",
"service": "biz_email_finder",
"columns": {
"company_domain": "Website"
},
"options": null,
"progress": {
"done": 500,
"total": 500,
"stoppable": false
},
"runs": [
{
"run_id": "ord_e01f8a2c41d9a7b3",
"status": "completed",
"rows": 500,
"credits": {
"deducted": 2500,
"held": 0,
"refunded": 900,
"charged": 1600
},
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_e01f8a2c41d9a7b3"
}
],
"created_at": "2026-11-10T10:05:02.000Z"
}
]
}Orders
Get Order Status
https://api.mapsdaddy.com/api/v1/orders/{order_id}One order's status, credits and result details: a Google Maps scrape, or an enrichment run. Poll it until status is completed.
Path parameters
- order_idstringrequired
The order_id of a scrape, or the run_id of an enrichment.
Returns
- order_idstring
Unique order ID.
- order_numbernumber
Short order number shown in your dashboard.
- servicestring
people for a Google Maps scrape, or the enrichment's key for an enrichment run.
peoplewebsite_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier - statusstring
Current status.
pendingqueuedprocessingcompletedcancelled - search_urlstring | null
Google Maps URL submitted with the order, if you sent one.
- categoriesstring[] | null
Business categories submitted with a Google Maps Scraper order.
- locationsstring[] | null
Locations submitted with a Google Maps Scraper order.
- placesstring[]
Older orders only. Always empty now.
- per_searchnumber | null
The most businesses to take from each search, if you set a limit.
- deep_searchboolean
true when the order was a deep search (the area swept for more than Google's ~120 results).
- output_formatstring
File format of the delivery.
csvxlsx - input_fileobject | null
Enrichment runs: the rows sent to the service (name, rows, size_bytes). null on scrapes.
- results_file_namestring
Name given to the order and its file.
- requested_countnumber
Rows sent for an enrichment run. 0 on the Google Maps Scraper, which has a flat price.
- delivered_countnumber
Results delivered (0 until completed).
- verify_emailsboolean
Older orders only. Always false now.
- notestring | null
Notes sent with the order.
- creditsobject
deducted (taken from your balance when you order), held (set aside until the order finishes), refunded (returned for rows with no result, or if the order is cancelled) and charged (final cost, 0 until the order finishes).
- status_urlstring
This endpoint.
- download_urlstring | null
Public download link for the first file. It works without an API key. null while processing, after cancellation or once the file expired.
- fileobject | null
name, rows and size_bytes of the first delivered file.
- filesarray
Every delivered file: name, size_bytes and download_url.
- callback_urlstring | null
Webhook URL attached to the order.
- cancel_reasonstring | null
Why the order was cancelled, when it was.
- created_atstring
ISO 8601 timestamp of order creation.
- delivered_atstring | null
ISO 8601 timestamp of delivery.
- expires_atstring | null
When the delivered file stops being downloadable.
- delivery_expiredboolean
true once expires_at has passed.
Status codes
- 200Success
- 404Order not found
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- You can only read your own account's orders; anything else returns 404.
- queued means it's waiting its turn; processing means it's running.
- Polling every 10 seconds is fine, or use callback_url to be notified instead.
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"order_id": "ord_8f2c41d9a7b34e01",
"order_number": 1042,
"service": "people",
"status": "completed",
"search_url": null,
"categories": [
"Dentist",
"Orthodontist"
],
"locations": [
"Austin, Texas, United States",
"Cedar Park, Texas, United States"
],
"places": [],
"per_search": null,
"output_format": "csv",
"input_file": null,
"results_file_name": "dentists-austin",
"requested_count": 0,
"delivered_count": 684,
"verify_emails": false,
"note": null,
"credits": {
"deducted": 40,
"held": 0,
"refunded": 0,
"charged": 40
},
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
"download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
"file": {
"name": "dentists-austin.csv",
"rows": 684,
"size_bytes": 264024
},
"files": [
{
"name": "dentists-austin.csv",
"size_bytes": 264024,
"download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW"
}
],
"callback_url": "https://example.com/webhooks/mapsdaddy",
"cancel_reason": null,
"created_at": "2026-11-10T09:24:11.000Z",
"delivered_at": "2026-11-10T09:24:52.000Z",
"expires_at": "2027-05-09T09:24:52.000Z",
"delivery_expired": false
}Orders
Download Result File
https://api.mapsdaddy.com/api/v1/orders/{order_id}/downloadDownload the file an order delivered, as it was delivered. To get a list with its enrichment results, use Download a List instead.
Path parameters
- order_idstringrequired
ID of a completed order.
Status codes
- 200The file
- 404Order not found
- 409File not ready yet
- 410File expired
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Add ?file=1 for the second file when an order has several. The first is ?file=0, the default.
- Returns 409 until the order is completed and 410 after the file expires (six months after delivery).
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01/download" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-L -o "dentists-austin.csv"search_business_type,search_business_locations,Business Name,Website,Address,Phone Number,Category,Rating,Rating Count
Dentist,"Austin, Texas, United States",Lone Star Smiles,https://lonestarsmiles.example.com/,"1200 S Lamar Blvd, Austin, TX 78704",+1 512-555-0142,Dentist,4.8,312Orders
List Orders
https://api.mapsdaddy.com/api/v1/ordersEvery order, newest first: scrapes, Local Business Database lists and enrichment runs. For just your lists, use List Lists.
Query parameters
- statusstringoptional
Only orders with this status.
pendingqueuedprocessingcompletedcancelled - limitnumberoptional
Page size, 1–100. Defaults to 20.
- offsetnumberoptional
How many to skip. Defaults to 0.
Returns
- dataarray
Orders in the same shape as Get Order Status.
- total / has_morenumber / boolean
For paging with limit and offset.
Status codes
- 200Success
- 400Invalid status filter
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Combine limit and offset to page through results; stop when has_more is false.
curl "https://api.mapsdaddy.com/api/v1/orders?status=completed&limit=20" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"data": [
{
"order_id": "ord_8f2c41d9a7b34e01",
"order_number": 1042,
"service": "people",
"status": "completed",
"search_url": null,
"categories": [
"Dentist",
"Orthodontist"
],
"locations": [
"Austin, Texas, United States",
"Cedar Park, Texas, United States"
],
"places": [],
"per_search": null,
"output_format": "csv",
"input_file": null,
"results_file_name": "dentists-austin",
"requested_count": 0,
"delivered_count": 684,
"verify_emails": false,
"note": null,
"credits": {
"deducted": 40,
"held": 0,
"refunded": 0,
"charged": 40
},
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
"download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
"file": {
"name": "dentists-austin.csv",
"rows": 684,
"size_bytes": 264024
},
"files": [
{
"name": "dentists-austin.csv",
"size_bytes": 264024,
"download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW"
}
],
"callback_url": "https://example.com/webhooks/mapsdaddy",
"cancel_reason": null,
"created_at": "2026-11-10T09:24:11.000Z",
"delivered_at": "2026-11-10T09:24:52.000Z",
"expires_at": "2027-05-09T09:24:52.000Z",
"delivery_expired": false
}
],
"total": 37,
"limit": 20,
"offset": 0,
"has_more": true
}Account
Get Account & Balance
https://api.mapsdaddy.com/api/v1/meThe account that owns the API key and its credit balance. Handy as a connection test.
Parameters
No parameters. Just send the Authorization header.
Returns
- id / name / emailstring
The account.
- credits.availablenumber
Credits available to spend.
Status codes
- 200Success
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Check credits.available before big orders to avoid 402 responses.
curl "https://api.mapsdaddy.com/api/v1/me" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"id": "usr_4b1d9e2a",
"name": "Alex Morgan",
"email": "alex@example.com",
"credits": {
"available": 12400
}
}Account
Get Pricing
https://api.mapsdaddy.com/api/v1/pricingLive credit costs for every service, the price of credits and the credit packages, so you can work out a cost before spending.
Parameters
No parameters. Just send the Authorization header.
Returns
- usd_per_1000_creditsnumber
Base price in USD of 1,000 credits, for custom amounts. Packages include bonus credits.
- packagesarray
Credit packages: name, credits, bonus_credits and price_usd.
- services[].servicestring
Service key.
google_maps_scraperbusiness_databasewebsite_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier - services[].credits_per_searchnumber
Google Maps Scraper: credits per search.
- services[].credits_per_deep_searchnumber
Google Maps Scraper: credits per deep search (deep_search: true).
- services[].credits_per_businessnumber
Local Business Database: credits per business exported (once per account).
- services[].credits_per_resultnumber
Enrich Contacts: credits per result found, or per row checked.
- services[].enabledboolean
false when a service is switched off for now.
Status codes
- 200Success
- 401API key missing or invalid
- 429Rate limit exceeded
Good to know
- Google Maps Scraper credits = credits_per_search × searches (categories × locations), or credits_per_deep_search × searches for a deep search.
- Local Business Database credits = credits_per_business × businesses you haven't exported before. Price an Export gives the exact number.
- Enrichment credits = credits_per_result × results found. A dry run gives the most it could cost.
curl "https://api.mapsdaddy.com/api/v1/pricing" \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"{
"usd_per_1000_credits": 3,
"packages": [
{
"name": "Starter",
"credits": 5000,
"bonus_credits": 0,
"price_usd": 15
},
{
"name": "Growth",
"credits": 10000,
"bonus_credits": 1000,
"price_usd": 30
},
{
"name": "Pro",
"credits": 25000,
"bonus_credits": 5000,
"price_usd": 75
},
{
"name": "Scale",
"credits": 50000,
"bonus_credits": 12500,
"price_usd": 150
},
{
"name": "Business",
"credits": 75000,
"bonus_credits": 20000,
"price_usd": 225
},
{
"name": "Enterprise",
"credits": 100000,
"bonus_credits": 30000,
"price_usd": 300
}
],
"services": [
{
"service": "google_maps_scraper",
"endpoint": "/google-maps-scraper",
"credits_per_search": 10,
"credits_per_deep_search": 30,
"enabled": true
},
{
"service": "business_database",
"endpoint": "/business-database/exports",
"credits_per_business": 0.5,
"max_per_export": 100000,
"enabled": true
},
{
"service": "email_finder",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 5,
"charged_for": "results_found",
"enabled": true
},
{
"service": "personal_email",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 10,
"charged_for": "results_found",
"enabled": true
},
{
"service": "phone_finder",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 20,
"charged_for": "results_found",
"enabled": true
},
{
"service": "email_verifier",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 0.5,
"charged_for": "rows_checked",
"enabled": true
},
{
"service": "website_finder",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 2,
"charged_for": "results_found",
"enabled": true
},
{
"service": "biz_email_finder",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 5,
"charged_for": "results_found",
"enabled": true
},
{
"service": "social_finder",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 3,
"charged_for": "results_found",
"enabled": true
},
{
"service": "contact_enrichment",
"endpoint": "/lists/{list_id}/enrichments",
"credits_per_result": 20,
"charged_for": "results_found",
"enabled": true
}
]
}Webhook events
Pass a public HTTPS callback_url when you create a Google Maps Scraper order and we'll POST a JSON event to it whenever the order changes. Reply with any 2xx within 10 seconds. For Local Business Database exports and enrichment runs, check their status_url instead.
Events
- order.processingevent
The scrape started.
- order.deliveredevent
The file is ready. download_url is included.
- order.cancelledevent
The order was cancelled and its credits refunded.
Headers
- X-MapsDaddy-Eventstring
The event name.
- X-MapsDaddy-Signaturestring
sha256= followed by the HMAC-SHA256 of the raw body, keyed with your callback_signing_secret.
Failed deliveries are retried up to 5 times with exponential backoff (30s, 2m, 8m, 32m).
{
"id": "whd_7c2e9a41f0b84d16a3c5",
"event": "order.delivered",
"created_at": "2026-11-10T09:24:52.000Z",
"data": {
"order_id": "ord_8f2c41d9a7b34e01",
"order_number": 1042,
"service": "people",
"status": "completed",
"delivered_count": 684,
"credits": {
"deducted": 40,
"held": 0,
"refunded": 0,
"charged": 40
},
"status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
"download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
"cancel_reason": null
}
}Verify signatures
Every webhook is signed so you can be sure it came from us. Compute the HMAC-SHA256 of the raw request body with the callback_signing_secret you received when creating the order, and compare it to X-MapsDaddy-Signature using a constant-time check.
import crypto from "node:crypto";
// Use the raw request body exactly as received (before JSON parsing).
export function isValidSignature(rawBody, signatureHeader, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}