Skip to main content
POST
/
v2
/
discovery
/
start
Start discovery for new market
curl --request POST \
  --url https://rest.forestreet.com/v2/discovery/start \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "searchCriteria": {
    "marketName": "AI Healthcare Transcription Services",
    "userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
    "marketType": "service",
    "marketRole": "serviceProvider",
    "keywords": {
      "features": [
        "AI transcription",
        "speech-to-text",
        "healthcare"
      ],
      "user": [
        "healthcare",
        "enterprise",
        "hospitals"
      ],
      "synonyms": [
        "transcription",
        "dictation",
        "voice-to-text"
      ],
      "irrelevant": [
        "manual transcription",
        "human transcription"
      ]
    },
    "seedDomains": [],
    "count": 50,
    "assertions": null,
    "constraints": null,
    "projectKind": "first_pass",
    "performSearch": true,
    "locations": [
      {
        "countryCode": "GB",
        "countryName": "United Kingdom"
      }
    ]
  }
}'
{
  "metadata": {
    "marketId": 12345
  },
  "data": [
    {
      "jobId": 67890,
      "serviceName": "first_pass",
      "startTime": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Overview

This endpoint triggers an asynchronous AI-powered process that discovers companies based on your search criteria.
Workflow Step: This is Step 2 of the Market Research Workflow.
Important: This is an asynchronous process that can take 5-15 minutes to complete. Use the status endpoint to monitor progress.

​
Usage

The endpoint accepts search criteria and pipeline configuration options to control the discovery process:
  • Search Criteria: Market definition, keywords, and constraints
  • Pipeline Choices: Configuration for different analysis steps
  • Response: Job IDs for monitoring progress
Pipeline Configuration: Choose pipeline steps based on your research goals. Each step adds valuable insights but increases processing time.

​
Monitoring Progress

After starting discovery, monitor progress using the Get Discovery Job Status endpoint: 
GET /v2/discovery/12345/status
Polling Strategy: Check status every 30-60 seconds. The process typically takes 5-15 minutes depending on search complexity.

​
Best Practices

For Better Results: Use clear and specific search criteria generated from the Generate Search Criteria endpoint. Well-defined criteria help the discovery process return more relevant companies.
Important: Only one discovery process can run for a given market at a time. If you attempt to start discovery multiple times for the same market while a process is already running, your request will not succeed.

Authorizations

​
x-api-key
string
header
required

Pass a static API key for every request, provided by your customer support.

Body

application/json
​
searchCriteria
object
required
​
pipelineChoices
object

Choices for the publish pipeline.

Response

Discovery started successfully, returns the job id and status

​
metadata
object
required
​
data
object[]
required