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
I