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": [
      {
        "country": "GB",
        "address": null,
        "coordinates": null
      }
    ]
  }
}
'

import requests

url = "https://rest.forestreet.com/v2/discovery/start"

payload = { "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": None,
        "constraints": None,
        "projectKind": "first_pass",
        "performSearch": True,
        "locations": [
            {
                "country": "GB",
                "address": None,
                "coordinates": None
            }
        ]
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: [{country: 'GB', address: null, coordinates: null}]
    }
  })
};

fetch('https://rest.forestreet.com/v2/discovery/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://rest.forestreet.com/v2/discovery/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
                [
                                'country' => 'GB',
                                'address' => null,
                                'coordinates' => null
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://rest.forestreet.com/v2/discovery/start"

	payload := strings.NewReader("{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://rest.forestreet.com/v2/discovery/start")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://rest.forestreet.com/v2/discovery/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "marketId": 12345
  },
  "data": [
    {
      "jobId": 67890,
      "workflowId": 1,
      "workflowName": "first_pass",
      "startTime": "2024-01-15T10:30:00Z"
    }
  ]
}

{
  "success": false,
  "errorCode": "INVALID_INPUT",
  "message": "Invalid input provided"
}

{
  "success": false,
  "errorCode": "QUOTA_EXCEEDED",
  "message": "Payment Required - Team quota exceeded"
}

{
  "success": false,
  "errorCode": "FORBIDDEN",
  "message": "Forbidden"
}

{
  "success": false,
  "errorCode": "NOT_FOUND",
  "message": "Not Found"
}

{
  "success": false,
  "errorCode": "CONFLICT",
  "message": "Conflict"
}

{
  "success": false,
  "errorCode": "INTERNAL_SERVER_ERROR",
  "message": "Internal Server Error"
}

POST

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": [
      {
        "country": "GB",
        "address": null,
        "coordinates": null
      }
    ]
  }
}
'

import requests

url = "https://rest.forestreet.com/v2/discovery/start"

payload = { "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": None,
        "constraints": None,
        "projectKind": "first_pass",
        "performSearch": True,
        "locations": [
            {
                "country": "GB",
                "address": None,
                "coordinates": None
            }
        ]
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: [{country: 'GB', address: null, coordinates: null}]
    }
  })
};

fetch('https://rest.forestreet.com/v2/discovery/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://rest.forestreet.com/v2/discovery/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
                [
                                'country' => 'GB',
                                'address' => null,
                                'coordinates' => null
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://rest.forestreet.com/v2/discovery/start"

	payload := strings.NewReader("{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://rest.forestreet.com/v2/discovery/start")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://rest.forestreet.com/v2/discovery/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"searchCriteria\": {\n    \"marketName\": \"AI Healthcare Transcription Services\",\n    \"userPrompt\": \"Find AI-powered transcription services that serve enterprise healthcare customers\",\n    \"marketType\": \"service\",\n    \"marketRole\": \"serviceProvider\",\n    \"keywords\": {\n      \"features\": [\n        \"AI transcription\",\n        \"speech-to-text\",\n        \"healthcare\"\n      ],\n      \"user\": [\n        \"healthcare\",\n        \"enterprise\",\n        \"hospitals\"\n      ],\n      \"synonyms\": [\n        \"transcription\",\n        \"dictation\",\n        \"voice-to-text\"\n      ],\n      \"irrelevant\": [\n        \"manual transcription\",\n        \"human transcription\"\n      ]\n    },\n    \"seedDomains\": [],\n    \"count\": 50,\n    \"assertions\": null,\n    \"constraints\": null,\n    \"projectKind\": \"first_pass\",\n    \"performSearch\": true,\n    \"locations\": [\n      {\n        \"country\": \"GB\",\n        \"address\": null,\n        \"coordinates\": null\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "marketId": 12345
  },
  "data": [
    {
      "jobId": 67890,
      "workflowId": 1,
      "workflowName": "first_pass",
      "startTime": "2024-01-15T10:30:00Z"
    }
  ]
}

{
  "success": false,
  "errorCode": "INVALID_INPUT",
  "message": "Invalid input provided"
}

{
  "success": false,
  "errorCode": "QUOTA_EXCEEDED",
  "message": "Payment Required - Team quota exceeded"
}

{
  "success": false,
  "errorCode": "FORBIDDEN",
  "message": "Forbidden"
}

{
  "success": false,
  "errorCode": "NOT_FOUND",
  "message": "Not Found"
}

{
  "success": false,
  "errorCode": "CONFLICT",
  "message": "Conflict"
}

{
  "success": false,
  "errorCode": "INTERNAL_SERVER_ERROR",
  "message": "Internal Server Error"
}

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.

Query Parameters

teamId

number | null

Unique identifier for the team to use for this discovery.

collectionId

number | null

Unique identifier for the collection where the market will be created.

Body

application/json

searchCriteria

object

required

Show child attributes

pipelineChoices

object

Choices for the publish pipeline.

Show child attributes

Response

Discovery started successfully, returns the job id and status

metadata

object

required

Show child attributes

data

object[]

required

Show child attributes

Generate keywords for search Start discovery for existing market

⌘I

Quick Start

Guides

API Reference

UI Components

Start discovery for new market

Overview

Usage

Monitoring Progress

Best Practices

Authorizations

Query Parameters

Body

Response

​Overview

​Usage

​Monitoring Progress

​Best Practices

Authorizations

Query Parameters

Body

Response

Overview

Usage

Monitoring Progress

Best Practices