> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery Workflow

> Complete guide to conducting market research using Forestreet's AI-powered discovery and analysis platform.

This guide walks you through the complete market research process using Forestreet's API. The workflow consists of five
main phases, with the third phase being optional for quality control.

<Tip>
  **Before You Start**: Ensure you have proper authentication and access to the markets you want to research. All
  endpoints require valid authentication tokens.
</Tip>

## Overview

The discovery workflow follows this sequence:

1. **Search Criteria Generation** - Define what you're looking for
2. **Company Discovery** - Find relevant companies using AI
3. **Company Review** (Optional) - Review and include discovered companies
4. **Market Publishing** (Optional) - Publish your findings
5. **Market Analysis** - Gain insights from the discovered companies

<Steps>
  <Step>
    ## Phase 1: Search Criteria Generation

    **Purpose**: Convert your business question into structured search criteria that our AI can use to find relevant companies.

    ### Step 1.1: Generate Search Criteria

    Use the [Generate Search Criteria](/api-reference/endpoints/discovery/generate-search-criteria) endpoint to convert your natural language query into structured search parameters.

    ```bash theme={null}
    POST /v2/discovery/search-criteria
    Content-Type: application/json

    {
      "searchType": "marketSearch",
      "searchInput": "Find companies in the AI transcription services market that serve enterprise customers"
    }
    ```

    **Response**:

    ```json theme={null}
    {
      "searchCriteria": {
        "userPrompt": "Find companies in the AI transcription services market that serve enterprise customers",
        "marketName": "AI Transcription Services",
        "marketType": "service",
        "marketRole": "serviceProvider",
        "keywords": {
          "features": ["AI transcription", "speech-to-text", "enterprise"],
          "user": ["enterprise", "business", "corporate"],
          "synonyms": ["transcription", "dictation", "voice-to-text"],
          "irrelevant": ["manual transcription", "human transcription"]
        },
        "seedDomains": [],
        "projectKind": "first_pass",
        "locations": [
          {
            "countryCode": "GB",
            "countryName": "United Kingdom",
          }
        ]
      }
    }
    ```

    <Tip>
      **Pro Tip**: Be specific in your search input. Instead of "AI companies", try "AI-powered transcription services for enterprise customers in the healthcare sector."
    </Tip>

    ### Step 1.2: Refine Keywords (Optional)

    Use the [Generate Keywords](/api-reference/endpoints/discovery/generate-keywords-for-search) endpoint to get AI-suggested keywords for your search criteria.

    <Note>
      This step is optional but recommended for better discovery results. The AI will suggest additional relevant keywords and help refine your search.
    </Note>
  </Step>

  <Step>
    ## Phase 2: Company Discovery

    **Purpose**: Use the generated search criteria to discover relevant companies using AI-powered algorithms.

    ### Step 2.1: Start Discovery Process

    Use the [Start Discovery](/api-reference/endpoints/discovery/start-discovery-for-new-market) endpoint to initiate the company discovery process.

    <Note>
      If you set <code>skipDiscoveryReview</code> to <code>true</code> in <code>pipelineChoices</code>, the workflow will skip the company review phase and jump directly to <strong>Phase 5: Market Analysis</strong>.
    </Note>

    ```bash theme={null}
    POST /v2/discovery/12345/start
    Content-Type: application/json

    {
      "searchCriteria": {
        "marketName": "AI Transcription Services",
        "userPrompt": "Find companies in the AI transcription services market that serve enterprise customers",
        "marketType": "service",
        "marketRole": "serviceProvider",
        "keywords": {
          "features": ["AI transcription", "speech-to-text", "enterprise"],
          "user": ["enterprise", "business", "corporate"],
          "synonyms": ["transcription", "dictation", "voice-to-text"],
          "irrelevant": ["manual transcription", "human transcription"]
        },
        "seedDomains": [],
        "count": 50,
        "performSearch": true,
        "locations": [
          {
           "countryCode": "GB",
           "countryName": "United Kingdom",
          }
        ]
      },
      "pipelineChoices": {
        "skipDiscoveryReview": false
      }
    }
    ```

    **Response**:

    ```json theme={null}
    {
      "metadata": {
        "marketId": 12345,
      },
      "data": [
        {
          "jobId": 67890,
          "workflowName": "first_pass",
          "startTime": "2024-01-15T10:30:00Z",
        },
      ]
    }
    ```

    <Warning>
      **Important**: The discovery process runs asynchronously and can take 10-15 minutes. Do not make multiple requests for the same market while discovery is in progress.
    </Warning>

    ### Step 2.2: Monitor Discovery Progress

    Use the [Get Job Status](/api-reference/endpoints/discovery/get-job-status) endpoint to check the progress of your discovery job.

    ```bash theme={null}
    GET /v2/discovery/{marketId}/jobs
    ```

    **Response**:

    ```json theme={null}
    {
      "metadata": {
        "marketId": 12345,
      },
      "data": [
        {
          "jobId": 67890,
          "jobProgress": 0,
          "workflowName": "first_pass",
          "status": "running",
          "startTime": "2024-01-15T10:30:00Z",
          "endTime": null
        },
      ]
    }
    ```

    <Tip>
      **Polling Strategy**: Check status every 30-60 seconds. The process typically takes 10-15 minutes depending on the complexity of your search criteria.
    </Tip>
  </Step>

  <Step>
    ## Phase 3: Company Review (Optional)

    **Purpose**: Review and include discovered companies before publishing for quality control.

    <Note>
      **Optional Step**: This phase is only needed if you set `skipDiscoveryReview: false` in your pipeline choices. If you set it to `true`, you can skip directly to Phase 4.
    </Note>

    ### Step 3.1: Review Discovered Companies

    Once discovery is complete, review the discovered companies and include them using the [Update Company Review Status](/api-reference/endpoints/discovery/update-company-review-status) endpoint:

    ```bash theme={null}
    PATCH /v2/discovery/12345/companies/reviews
    Content-Type: application/json

    {
      "reviewStatus": "include",
      "target": {
        "mode": "partial",
        "domains": [
          "new-company.com",
          "startup-ai.com"
        ]
      }
    }
    ```

    <Tip>
      **Review Process**: This step is optional but recommended for quality control. You can include or exclude discovered companies.
    </Tip>

    ### Step 3.2: Retrieve Search Criteria

    Use the [Get Search Criteria](/api-reference/endpoints/discovery/get-search-criteria) endpoint to review the criteria used for discovery.

    ```bash theme={null}
    GET /v2/discovery/12345/search-criteria
    ```

    ### Step 3.3: Check Search History

    Use the [Get Search Criteria History](/api-reference/endpoints/discovery/get-search-criteria-history) endpoint to view previous search criteria iterations.

    ```bash theme={null}
    GET /v2/discovery/12345/search-criteria/history
    ```
  </Step>

  <Step>
    ## Phase 4: Market Publishing

    **Purpose**: Publish the discovered companies and trigger market analysis and enrichment.

    ### Step 4.1: Publish Market

    <Note>
      **Optional Step**: This phase is only needed if you set `skipDiscoveryReview: false` in your pipeline choices during **Step 2 Start Discovery Process**. If you set it to `true`, you can skip directly to Phase 5.
    </Note>

    Once discovery is complete (and review is done if applicable), use the [Publish Market](/api-reference/endpoints/discovery/publish-a-market) endpoint to trigger market analysis and enrichment.

    ```bash theme={null}
    POST /v2/discovery/12345/publish
    ```

    **Response**:

    ```json theme={null}
    "metadata": {
      "marketId": 12345,
    },
    "data": [
      {
        "jobId": 67890,
        "workflowName": "enrichment",
        "startTime": "2024-01-15T10:30:00Z",
      },
      {
        "jobId": 67891,
        "workflowName": "scrape",
        "startTime": "2024-01-15T10:30:00Z",
      },
      {
        "jobId": 67892,
        "workflowName": "web_traffic",
        "startTime": "2024-01-15T10:30:00Z",
      },
    ],
    ```

    ### Step 4.2: Monitor Publish Progress

    Use the [Get Job Status](/api-reference/endpoints/discovery/get-job-status) endpoint to check the progress of your publish job.

    ```bash theme={null}
    GET /v2/markets/{marketId}/jobs
    ```
  </Step>

  <Step>
    ## Phase 5: Accessing Published Market

    **Purpose**: Access and utilise the enriched data and insights from your published market.

    ### Step 5: Access Your Published Market

    Once publishing is complete, you can access your market through the Markets API endpoints:

    ```bash theme={null}

    # Get companies in the market
    GET /v2/markets/12345/companies

    # Get ESG data
    GET /v2/markets/12345/esg

    ```
  </Step>
</Steps>

### Error Handling

<Warning>
  **Common Issues**: - **409 Conflict**: Discovery already in progress for this market - **403 Forbidden**: Insufficient
  permissions for the market - **404 Not Found**: Market doesn't exist or you don't have access
</Warning>

### Best Practices

<Tip>
  **For Better Results**: 1. **Be Specific**: Use detailed, specific search criteria 2. **Use Keywords**: Leverage the
  keyword generation feature 3. **Monitor Progress**: Check status regularly during long-running processes 4. **Review
  Companies**: Take time to review discovered companies before publishing
</Tip>

## Next Steps

Once your market is published, you can:

* **Export Data**: Use the export endpoints to get CSV/Excel files
* **Track News**: Monitor news and updates for companies in your market
* **Share Insights**: Use the UI components to visualize and share your findings

For detailed API reference, see the [Discovery Endpoints](/api-reference/endpoints/discovery) section.