API, MCP & CLI Automation

Run the same workflow from AI and code.

Use REST to connect your application, MCP to connect a compatible AI assistant, or the CLI from your terminal. Start searches or enrich existing websites, then retrieve saved results.

Get Started Explore the details

Available on Scale and Max. Use a MapBulk API key in your own application, compatible AI client or CLI. Searches complete asynchronously.

API and MCP input symbols merge into one job that produces one result list.

Ask for work. Follow it. Retrieve the result.

A request creates saved work, not an instant finished list. Keep the search ID, check progress, read results in pages and wait for your export to be ready.

Asynchronous work with a stable job identity
API, MCP, CLI and Dashboard read the same saved campaigns
Results and credit balance are shared across surfaces

Four clear stages show Create, Track, Review and Export along one connected path.

A lost reply should not mean duplicate work.

Repeat an eligible operation with the same idempotency key and unchanged payload. Read its state before deciding whether a genuinely new request is needed.

Retry the same operation, not a new job
Inspect issues before retrying a permanent error
Replays do not add duplicate charges

Two matching requests with the same idempotency key converge on one existing search job without a duplicate charge.

Current tools. One complete working loop.

Discovery, enrichment, review, control and export are available without hiding the job lifecycle.

Scroll sideways for all columns

MCP tool	Purpose
list_business_categories	Find category IDs and catalog version
search_businesses	Start discovery
get_search_job	Read progress
get_search_results	Page through results
list_leads	Review workspace leads
get_search_issues	Inspect issues
cancel_search	Cancel unfinished work
retry_search	Retry eligible work
get_usage	Read usage and credits
enrich_businesses	Enrich leads or an existing list
export_results	Prepare selected results for export

REST example · read usage

curl https://api.mapbulk.com/v1/usage \
  -H "Authorization: Bearer $MAPBULK_API_KEY"

Example request to a compatible AI assistant: “Find roofing contractors in Dallas, enrich their websites, then export the businesses with emails.” The assistant may need to check progress before the results are ready. Use your own API key; never expose it in public frontend code. MCP connection formats differ by client. These examples do not execute requests.

A clearer picture, including the limits.

Can the API or MCP do enrichment without Maps discovery?

Yes. Enrich an existing list without paying a discovery fee for that imported data. The same accepted-email credit rule applies.

Does MapBulk depend on the assistant remembering the search?

No. The search is saved in MapBulk. A compatible client can use a fresh MCP session to access the same job.

Does automation include sending emails?

No. The workflow covers discovery, enrichment, review, control and export. Email sending is outside this product.

How can I submit my own websites?

Use the REST create → batch upload → complete import flow, then request enrichment. With MCP, enrich an existing search or send an inline list of up to 1,000 businesses; each inline row needs external_id and website_url. Larger imports use the batch workflow.

How are large results retrieved?

Poll saved search progress and read up to 20 records per results page. Request CSV, JSON or XLSX and wait for the artifact to be ready. Use has_email when an email-only or no-email result selection is wanted.

API, MCP & CLI Automation

See how it fits into your next business list.

Get Started