> ## Documentation Index
> Fetch the complete documentation index at: https://www.mapsdata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a search

> Queue a Google Maps business search and contact enrichment job.

Creates an asynchronous search backed by the same queue, workers, credit balance, and result store as the Mapsdata dashboard. The response is `202 Accepted`.

<ParamField header="Idempotency-Key" type="string" required>
  A stable unique value for one logical search. Use a UUID or a readable key such as `ny-plumbers-2026-10-01`. Required in production.
</ParamField>

<ParamField body="name" type="string">
  Dashboard list name, up to 200 characters. Defaults to `{query} in {location}`.
</ParamField>

<ParamField body="input" type="object" required>
  Search input shared with the web app.

  <Expandable title="input fields">
    <ParamField body="input.query" type="string" required>Business type or search phrase, up to 300 characters.</ParamField>
    <ParamField body="input.location" type="string" required>Use the `label` returned by `GET /locations`, for example `New York, New York`.</ParamField>
    <ParamField body="input.countryCode" type="string">Uppercase ISO two-letter country code, for example `US`.</ParamField>
    <ParamField body="input.maxResults" type="integer" default="100">Requested businesses. Minimum `100`; current product maximum `700`, further bounded by plan and available credits.</ParamField>
    <ParamField body="input.language" type="string" default="en">Two- or three-letter language code, optionally followed by a locale.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="enrich_contacts" type="boolean" default="true">
  Set `true` for the full discovery and enrichment pipeline. Set `false` for Google Maps business discovery only; returned enrichment status fields are `not_requested`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://www.mapsdata.io/api/v1/searches" \
    -H "Content-Type: application/json" \
    -H "x-api-key: md_live_your_key" \
    -H "Idempotency-Key: ny-plumbers-2026-10-01" \
    -d '{
      "name": "New York plumbers",
      "input": {
        "query": "plumbers",
        "location": "New York, New York",
        "countryCode": "US",
        "maxResults": 100,
        "language": "en"
      },
      "enrich_contacts": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "job_id": "c15dbb36-5a56-4720-b1af-b388bcaf78dc",
    "status": "queued",
    "credits_reserved": 100,
    "message": "Search accepted. It is visible in your Mapsdata dashboard."
  }
  ```
</ResponseExample>

## Credits and rejection behavior

* Free accounts receive one search of up to 100 requested businesses. The free search reserves 100 credits.
* Active paid accounts reserve the requested `maxResults` immediately.
* Requests below 100 return `422` before a job is created or credits are reserved.
* If 700 credits remain and `maxResults` is 1,000, the API returns `402` and explains that only 700 remain.
* A request above the plan allowance or the 700-business product ceiling returns `403`.
* Rejected requests create no job and deduct no credits.
* Failed jobs follow the dashboard's refund behavior; successful searches keep the reserved charge even if fewer businesses are returned.

## Choose the workflow

| Goal | Request |
| - | - |
| Search Google Maps only | `POST /searches` with `enrich_contacts: false` |
| Search and enrich every result | `POST /searches` with `enrich_contacts: true` |
| Enrich businesses you already have | [`POST /enrichments`](/docs/endpoints/create-enrichment) |

With `enrich_contacts: false`, Mapsdata still returns business name, category, address, phone, website, rating, review count, status, and Maps identifiers when the discovery provider supplies them. It skips website crawling, people and email discovery, public-source enrichment, and email verification. The job completes directly after import.

## Safe retries

Sending the same body and idempotency key returns the existing job without charging twice. Reusing the key with a different name, input, or enrichment setting returns `409 Conflict`.

<div className="callout mint-my-5 mint-rounded-xl mint-border mint-border-[#656c2e]/30 mint-bg-[#656c2e]/10 mint-px-5 mint-py-4 mint-text-sm mint-text-[#4d5321]">
  API-created jobs appear in Dashboard and Lead lists immediately. Partial businesses are imported and shown in the UI while the job is still running.
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.