Prospect Discovery API | Insites Help Center

This page explains how to use our API to search for businesses across multiple industries and locations, filter the results and audit selected businesses.

All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.

How a Prospect Discovery search works

Prospect Discovery searches run in the background. Starting a search returns a search id, which you can use to fetch its status and results.

The process has three steps:

Start a search using your chosen industries and locations.
Fetch the results every few seconds until the search finishes, applying any filters you need.
Start audits for the businesses you want to analyse.

A search moves through these statuses: pending → running → complete. Its status will be failed if it could not be completed.

Searches do not use credits. Audits use one report credit each.

Start a new search

Method: POST

Endpoint: https://api.insites.com/api/v1/prospect-searches

Request body should be JSON encoded, and can include the following fields:

Property	Definition	Required
`industries`	Array of strings – Industries to search for, e.g. `["plumbers", "electricians"]`. Maximum of 5.	Yes
`locations`	Array of strings – Locations to search in, e.g. `["Leeds", "Bradford"]`. Supports towns, cities, regions and postcodes. Maximum of 5.	Yes
`limit`	Integer – Maximum number of businesses to collect, from 1 to 200. Defaults to 200. A smaller limit allows the search to finish sooner.	No
`language`	String – Language code used to look up locations, e.g. `en`.	No

Each industry is searched in each location, up to a maximum of 25 industry and location combinations. The search can collect up to 200 businesses in total.

You can also include an optional Idempotency-Key header to prevent retries from creating duplicate searches. See Idempotency below.

Example

curl --request POST "https://api.insites.com/api/v1/prospect-searches" \   --header "api-key:[YOUR API KEY]" \   --header "Content-Type: application/json" \   --data '{     "industries": ["plumbers"],     "locations": ["Leeds"],     "limit": 50   }'

Expected response

If successful, you would expect a 202 response containing the search id.

The response also includes a Location header pointing to the search, which can be used when polling.

Fetch a search and its results

Method: GET

Endpoint: https://api.insites.com/api/v1/prospect-searches/[ID]

Returns the search status and any results collected so far.

While the search is in progress, the API returns a 202 response. Once the search has finished, it returns a 200 response.

If a location cannot be found, it is listed in locations_not_found. The search continues for the remaining locations.

Example

curl "https://api.insites.com/api/v1/prospect-searches/[ID]" \   --header "api-key:[YOUR API KEY]"

Filtering results

You can include the following optional query parameters when fetching a search:

Property	Supported values	Definition
`website`	`has`, `missing`	Whether the business has a website.
`phone`	`has`, `missing`	Whether the business has a phone number.
`address`	`has`, `missing`	Whether the business has an address.
`photos`	`has`, `missing`	Whether the business has photos.
`utm`	`has`, `missing`	Whether the business has UTM tracking.
`claimed`	`claimed`, `unclaimed`	Whether the Google Business Profile is claimed.
`categories`	Comma-separated Google categories, e.g. `Plumber,Heating contractor`	Businesses matching any of the supplied categories.
`rating`	`under_3`, `under_4`, `4_plus`, `4.5_plus`	Filter by rating.
`reviews`	`none`, `under_10`, `under_50`, `under_100`, `100_plus`	Filter by review count.
`rank`	`top_3`, `top_10`, `top_20`, `not_ranked`	Filter by organic Google position.
`analysed`	`yes`, `no`	Whether the business has already been audited by your account.

Filters are combined using AND. For example, using website=has and claimed=unclaimed returns businesses that have a website and an unclaimed Google Business Profile.

If none of the results contain the data needed for a filter, that filter is skipped and listed under filters.ignored. Check this field to confirm which filters were applied.

Example with filters

This request returns businesses with a website and an unclaimed Google Business Profile that have not already been audited by your account:

curl "https://api.insites.com/api/v1/prospect-searches/[ID]?website=has&claimed=unclaimed&analysed=no" \   --header "api-key:[YOUR API KEY]"

Result data

Each business result includes the following fields:

Property	Definition
`place_id`	The business’s place ID. Use this when requesting an audit.
`name`	Business name.
`website`	Business website.
`phone`	Phone number.
`address`	Business address.
`latitude`, `longitude`	Business coordinates.
`category`	Business category.
`rating`	Business rating.
`review_count`	Number of reviews.
`claimed`	Whether the Google Business Profile is claimed.
`has_photos`	Whether photos are present.
`has_utm`	Whether UTM tracking is present.
`organic_positions`	Organic Google ranking positions.
`report_id`	Your account’s latest audit for this business, or `null` if it has not been audited.
`found_by`	The industry and location searches that found the business.

The response also includes:

Property	Definition
`total_results`	Total number of businesses collected before filtering.
`matching_results`	Number of businesses matching the applied filters.
`filters.applied`	Filters applied to the results.
`filters.ignored`	Filters skipped because the required data was unavailable.

The report_id is checked each time you fetch the results, so it reflects the latest audit associated with the business in your account.

Expected responses

Code	Reason
`200`	The search has finished. Check `status` to determine the outcome.
`202`	The search is still in progress. Results collected so far are included.
`404`	The search was not found for your account.

There is no webhook for search completion. Fetch the search every few seconds until its status is complete or failed.

Audit selected businesses

Method: POST

Endpoint: https://api.insites.com/api/v1/prospect-searches/[ID]/audits

Starts audits for selected businesses from the search, using the same process as Analyse in the app.

Request body should be JSON encoded and include the following field:

Property	Definition	Required
`place_ids`	Array of strings – Place IDs of the businesses to audit. Maximum of 200.	Yes

Each audit uses one report credit. If your account does not have enough credits for the batch, the whole batch is refused.

Example

Replace the example place IDs with values returned by your search.

curl --request POST "https://api.insites.com/api/v1/prospect-searches/[ID]/audits" \   --header "api-key:[YOUR API KEY]" \   --header "Content-Type: application/json" \   --data '{     "place_ids": ["[PLACE ID 1]", "[PLACE ID 2]"]   }'

Expected response

If successful, you would expect a 202 response containing queued and skipped information.

Skipped businesses include their place_id and a reason:

Reason	Definition
`not_found`	The business is not part of this search.
`no_website`	The business has no website and your account does not support auditing without one.

As each audit gets under way, its report_id appears in the search results. You can then use the Audit API to check its status and fetch the audit data.

Idempotency

To make retries safe, send an Idempotency-Key header when starting a search or requesting audits.

--header "Idempotency-Key:[UNIQUE REQUEST KEY]"

If we receive a repeated request carrying the same key within 24 hours, we return the original result instead of creating a duplicate request.

Use a new key for each distinct request. When retrying the same request, reuse its original key.

If a request with the same key is still being processed, the API returns 409 with the code request_in_progress. Retry shortly afterwards.

Limits

Maximum of 5 industries and 5 locations per search.
Maximum of 200 businesses per search.
Maximum of 200 place IDs per audit request.
API keys are rate limited to 120 requests per minute.
Searches do not use credits. Each audit uses one report credit.

Errors

Errors return problem-details JSON containing a code that your integration can check.

Code	Error	Reason
`401`	Authentication error	The API key is invalid.
`402`	`insufficient_credits`	Your account does not have enough credits for the requested audits.
`404`	`prospect_search_not_found`	The search was not found for your account.
`409`	`request_in_progress`	A request using the same idempotency key is still being processed. Retry shortly afterwards.
`422`	`validation_failed`	One or more fields are invalid. The `errors` field contains details.
`422`	`nothing_to_audit`	There are no businesses eligible to audit in the request.