# POST /lead-gen/search

**Resource:** [Lead Generation](./lead-gen.md)  
**Scopes:** `lead-gen:write`  
**Write operation:** yes

Start a new Google Maps business search via Apify. For max_results <= 100 the search runs synchronously and returns results immediately. For 101-500 results, the search runs asynchronously -- poll GET /lead-gen/searches/:id until status is "completed". When scrape_contacts=true, the search always runs asynchronously (website scraping exceeds sync timeout), website_filter is forced to "withWebsite", and results without a valid email are dropped before saving (email guarantee) -- result_count reflects only kept rows. Results are automatically deduplicated and matched against existing CRM contacts (by phone) and customers (by website domain). Credits are charged based on max_results tier.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `query` | body | string | yes | Business type or search term, e.g. "electricians", "dentists", "restaurants" |
| `location` | body | string | yes | Location to search in, e.g. "Sydney, NSW", "Melbourne, VIC, Australia" |
| `max_results` | body | number | no | Max results to fetch (default 100, max 500). Credit tiers: 1-50, 51-100, 101-200, 201-500 |
| `radius_km` | body | number | no | Search radius in kilometres from the location centre |
| `saved_search_id` | body | uuid | no | UUID of a saved search to link this run to (updates run_count and last_run_at) |
| `place_minimum_stars` | body | string | no | Minimum Google rating: "two", "twoAndHalf", "three", "threeAndHalf", "four", "fourAndHalf" |
| `website_filter` | body | string | no | Filter by website presence: "allPlaces" (default), "withWebsite", "withoutWebsite" |
| `skip_closed_places` | body | boolean | no | Skip permanently closed businesses (default true) |
| `category_filter_words` | body | string[] | no | Only return results whose Google category contains one of these words |
| `scrape_contacts` | body | boolean | no | Scrape email addresses from business websites. When true: always runs async (returns immediately, poll for completion), forces website_filter to "withWebsite", drops results without a valid email (email guarantee), result_count reflects only kept rows. Use lead_gen_get_search to poll until status="completed". |
| `language` | body | string | no | Language code for results (default "en") |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/lead-gen/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "electricians",
    "location": "Sydney, NSW",
    "max_results": 50,
    "place_minimum_stars": "three",
    "website_filter": "withWebsite"
  }'
```

## Response example

```json
{
  "data": {
    "id": "8685d0d4-...",
    "status": "completed",
    "search_query": "electricians",
    "location": "Sydney, NSW",
    "max_results": 50,
    "result_count": 42,
    "new_result_count": 38,
    "already_in_crm_count": 4,
    "credits_charged": 10,
    "created_at": "2026-04-17T04:00:00Z",
    "completed_at": "2026-04-17T04:00:12Z",
    "results": [
      {
        "id": "a1b2c3d4-...",
        "business_name": "Sydney Electrical Services",
        "category": "Electrician",
        "address": "123 George St, Sydney NSW 2000",
        "city": "Sydney",
        "state": "NSW",
        "postal_code": "2000",
        "country_code": "AU",
        "phone": "+61299991234",
        "website": "https://sydneyelectrical.com.au",
        "email": null,
        "rating": 4.8,
        "reviews_count": 156,
        "google_maps_url": "https://maps.google.com/?cid=...",
        "match_status": "new",
        "matched_contact_id": null,
        "matched_customer_id": null,
        "imported": false,
        "imported_at": null
      }
    ],
    "meta": { "url": "https://app.trustpager.com/tools/lead-gen" }
  }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`