{"openapi":"3.1.0","info":{"title":"Prospect Cheap API","version":"1.0.0","description":"Prospect Cheap is an AI-powered Google Maps lead generation tool: it collects live local business leads from Google Maps and uses AI to enrich each one from its website with emails, the owner’s name and title, phone numbers and social profiles. Emails can be verified in one click on paid plans. Lists can be filtered, exported to CSV, sent straight to GoHighLevel, Instantly, Smartlead or lemlist, or pulled through a REST API and an MCP server for AI assistants. Pricing is one credit per lead found, with monthly plans from $29 and 150 free credits to start.","contact":{"email":"hello@prospectcheap.com","url":"https://prospectcheap.com/contact"}},"externalDocs":{"description":"API documentation","url":"https://prospectcheap.com/docs/create-search"},"servers":[{"url":"https://prospectcheap.com/api"}],"security":[{"apiKey":[]}],"paths":{"/credits":{"get":{"operationId":"getCredits","summary":"Credit balance","parameters":[{"name":"history","in":"query","description":"Set to 1 to add recent credit activity.","schema":{"type":"string"}}],"responses":{"200":{"description":"The balance.","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"integer"},"verify_credits":{"type":"integer","description":"Credits per email verified."},"can_verify":{"type":"boolean","description":"Email verification is for paid plans."}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/gmaps/lists":{"get":{"operationId":"listSearches","summary":"Your searches, newest first","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Searches and your credit balance.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSearch","summary":"Start a Google Maps search","description":"Runs in the background (usually 2–5 minutes): poll getSearch until status is \"completed\". One credit per lead found; unused reserved credits come back. Send niche + location for one search, or keywords for up to 50.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"niche":{"type":"string","description":"Kind of business, e.g. \"Dentist\". Required unless keywords is sent."},"location":{"type":"string","description":"City, region or area, e.g. \"Austin, Texas\". Required with niche."},"keywords":{"oneOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"string","description":"One per line."}],"description":"Bulk search. A keyword can name its own place: \"dentist in Austin, TX\"."},"country":{"type":"string","description":"Two-letter country code, e.g. \"US\"."},"maxResults":{"type":"integer","minimum":1,"maximum":500,"default":120,"description":"Per keyword in a bulk search."},"language":{"type":"string","default":"en"},"verifyEmails":{"type":"boolean","description":"Paid plans: verify the leads' emails when the search finishes (extra credits per email)."}}}}}},"responses":{"200":{"description":"The new search.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input; the message says what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or searches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The search could not start; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/gmaps/lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The search (list) id.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSearch","summary":"A search's status and one page of its leads","description":"status is running, importing, completed or failed. Poll every 15–30 seconds.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per","in":"query","schema":{"type":"integer","enum":[20,50,100],"default":50}},{"name":"q","in":"query","description":"Text search.","schema":{"type":"string"}},{"name":"filters","in":"query","description":"A JSON array of conditions, e.g. [{\"field\":\"email\",\"operator\":\"is_not_empty\"}].","schema":{"type":"string"}},{"name":"mode","in":"query","schema":{"type":"string","enum":["all","any"],"default":"all"}}],"responses":{"200":{"description":"The search, its leads and the total.","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"object"},"leads":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stopSearch","summary":"Stop a running search","description":"The leads found so far are kept and only they are charged; unused credits come back.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"const":"stop"}}}}}},"responses":{"200":{"description":"Stopping.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The search is not running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSearch","summary":"Delete a search and its leads","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/gmaps/lists/{id}/export":{"parameters":[{"name":"id","in":"path","required":true,"description":"The search (list) id.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"exportCsv","summary":"Export leads as CSV (free, up to 20,000 rows)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["all","simple","custom","instantly","gohighlevel"],"default":"all"},"columns":{"type":"array","items":{"type":"string"},"description":"For format \"custom\"."},"scope":{"type":"string","enum":["all","filtered","selected"],"default":"all"},"ids":{"type":"array","items":{"type":"string"}},"q":{"type":"string"},"filters":{"type":"array","maxItems":20,"description":"Conditions on lead fields.","items":{"type":"object","required":["field","operator"],"properties":{"field":{"type":"string","examples":["email","rating","owner_name","email_verified"]},"operator":{"type":"string","enum":["contains","not_contains","is","is_not","starts_with","ends_with","is_empty","is_not_empty","gt","gte","lt","lte","is_yes","is_no"]},"value":{"type":"string"}}}},"mode":{"type":"string","enum":["all","any"]},"emailOnly":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The CSV file.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/gmaps/{id}/verify":{"parameters":[{"name":"id","in":"path","required":true,"description":"The search (list) id.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getEmailVerification","summary":"Email verification progress","responses":{"200":{"description":"Counts of verified, not verified, unchecked and checking leads.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"verifyEmails","summary":"Verify the leads' emails (paid plans)","description":"Credits per unique address; leads without an email or already verified are free. Any size: big lists run in the background, so poll getEmailVerification. Then filter by email_verified.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"filters":{"type":"array","maxItems":20,"description":"Conditions on lead fields.","items":{"type":"object","required":["field","operator"],"properties":{"field":{"type":"string","examples":["email","rating","owner_name","email_verified"]},"operator":{"type":"string","enum":["contains","not_contains","is","is_not","starts_with","ends_with","is_empty","is_not_empty","gt","gte","lt","lte","is_yes","is_no"]},"value":{"type":"string"}}}},"mode":{"type":"string","enum":["all","any"]},"q":{"type":"string"},"recheck":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Started, or the results for a few addresses.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Email verification is for paid plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or searches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/gmaps/{id}/leads":{"parameters":[{"name":"id","in":"path","required":true,"description":"The search (list) id.","schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateLeads","summary":"Change leads (free, up to 500 per call)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"changes":{"type":"object"},"custom":{"type":"object","description":"Custom fields; null removes one."}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input; the message says what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteLeads","summary":"Delete chosen leads, or every lead matching filters","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"filters":{"type":"array","maxItems":20,"description":"Conditions on lead fields.","items":{"type":"object","required":["field","operator"],"properties":{"field":{"type":"string","examples":["email","rating","owner_name","email_verified"]},"operator":{"type":"string","enum":["contains","not_contains","is","is_not","starts_with","ends_with","is_empty","is_not_empty","gt","gte","lt","lte","is_yes","is_no"]},"value":{"type":"string"}}}},"mode":{"type":"string","enum":["all","any"]},"q":{"type":"string"},"confirm":{"type":"boolean","description":"Required (true) when deleting by filters."}}}}}},"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input; the message says what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addOrDedupeLeads","summary":"Add leads by hand, or remove duplicates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"enum":["add","dedupe"]},"leads":{"type":"array","items":{"type":"object"}},"by":{"enum":["email","website","phone","name"]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input; the message says what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The search does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key (pc_live_…) from Connections → API & MCP."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}