# Authentication
Source: https://docs.forestreet.com/api-reference/authentication

How to authenticate your API requests

Most interactions with our API require authentication to ensure that only authorized users can access or modify data.
There are multiple ways to be authenticated.

> **API Header Key**
>
> The simplest way to authenticate your API requests is by using an API token. This token should be included in the
> `x-api-key` header of your requests:
>
> ```sh Shell theme={null}
> curl -H 'x-api-key: <api_token>' <host>/v2/users/me
> ```
>
> ```javascript Javascript Fetch theme={null}
> import { fetch } from "node-fetch";
>
> const authHeaders = {
>   "x-api-key": "<api_token>",
> };
> await fetch("<host>/v2/users/me", {
>   method: "GET",
>   headers: authHeaders,
> });
> ```
>
> ```javascript Javascript Axios theme={null}
> import axios from "axios";
>
> const authHeaders = {
>   "x-api-key": "<api_token>",
> };
> await axios.get("<host>/v2/users/me", {
>   headers: authHeaders,
> });
> ```
>
> ```python Python Blocking theme={null}
> import requests
> auth_headers = {
>     'x-api-key': '<api_token>'
> }
> response = requests.get('<host>/v2/users/me', headers=auth_headers)
> ```
>
> ```python Python Async theme={null}
> import httpx
> auth_headers = {
>     'x-api-key': '<api_token>'
> }
> async with httpx.AsyncClient() as client:
>     response = await client.get('<host>/v2/users/me', headers=auth_headers)
> ```
>
> This authentication is stateless, meaning that the authentication is only valid for the current request. All subsequent
> requests must include the API token in the header. This prevents the need for timed session management.
>
> These keys should be kept confidential. If compromised, it's crucial to revoke and generate a new token immediately. To
> do this, reach out to us at [info@forestreet.com](mailto:info@forestreet.com).
>
> Each token is associated with specific permissions, granting access to various levels and types of data. Speak to us
> about the various levels of data access that you require.
>
> > [!TIP]
> >
> > This method is suitable for:
> >
> > * backend services
> > * server-side applications
> > * scripts
>
> > [!WARNING]
> >
> > This method is **not suitable** for: - client-side applications (e.g., web browsers, mobile apps) as it exposes the
> > API key

> **Email, Password and Cookie Session**
>
> If you have an user interface which allows users to log in, you can authenticate users using their input credentials.
>
> This is done through the [`POST /v2/auth/sign-in`](/api-reference/endpoints/auth/sign-in) endpoint:
>
> ```sh Shell theme={null}
> curl -X POST -H 'Content-Type: application/json' -d '{"email": "<email>", "password": "<password>"}' <host>/v2/auth/sign-in
> ```
>
> ```javascript Javascript Fetch theme={null}
> import { fetch } from "node-fetch";
>
> const response = await fetch("<host>/v2/auth/sign-in", {
>   method: "POST",
>   headers: {
>     "Content-Type": "application/json",
>   },
>   body: JSON.stringify({
>     email: "<email>",
>     password: "<password>",
>   }),
> });
> ```
>
> ```javascript Javascript Axios theme={null}
> import axios from "axios";
>
> const response = await axios.post("<host>/v2/auth/sign-in", {
>   email: "<email>",
>   password: "<password>",
> });
> ```
>
> ```python Python Blocking theme={null}
> import requests
> with requests.Session() as session:
>     response = session.post('<host>/v2/auth/sign-in', json={
>         'email': '<email>',
>         'password': '<password>'
>     })
>     # Any subsequent requests using this session will include the cookie automatically
> ```
>
> ```python Python Async theme={null}
> import httpx
> async with httpx.AsyncClient() as client:
>     response = await client.post('<host>/v2/auth/sign-in', json={
>         'email': '<email>',
>         'password': '<password>'
>     })
>     # Any subsequent requests using this client will include the cookie automatically
> ```
>
> The response will include a `Set-Cookie` header with a session cookie. This cookie should be stored in the user's
> browser or application, and included in subsequent requests to the API. The cookie will be used to authenticate the user
> for the duration of the session.
>
> > [!TIP]
> >
> > This method is suitable for: - web applications - mobile applications - any application where users log in with email
> > and password
>
> > [!WARNING]
> >
> > This method is **not suitable** for: - backend services or scripts, as it requires storing user credentials which can
> > lead to security issues

> **Session ID**
>
> For [iFrame integrations](/api-reference/guides/iframe-integration), you will need to be able to authenticate your user in a browser
> for a limited time period, without
>
> * exposing your API key to the frontend, or
> * the user having their login credentials at all.
>
> This is done through the [`GET /v2/auth/session`](/api-reference/endpoints/auth/get-session-id) endpoint:
>
> ```sh Shell theme={null}
> curl -H 'x-api-key: <api_token>' <host>/v2/auth/session
> ```
>
> ```javascript Javascript Fetch theme={null}
> import { fetch } from "node-fetch";
>
> const authHeaders = {
>   "x-api-key": "<api_token>",
> };
> const response = await fetch("<host>/v2/auth/session", {
>   method: "GET",
>   headers: authHeaders,
> });
> ```
>
> ```javascript Javascript Axios theme={null}
> import axios from "axios";
>
> const authHeaders = {
>   "x-api-key": "<api_token>",
> };
> const response = await axios.get("<host>/v2/auth/session", {
>   headers: authHeaders,
> });
> ```
>
> ```python Python Blocking theme={null}
> import requests
> auth_headers = {
>     'x-api-key': '<api_token>'
> }
> response = requests.get('<host>/v2/auth/session', headers=auth_headers)
> ```
>
> ```python Python Async theme={null}
> import httpx
> auth_headers = {
>     'x-api-key': '<api_token>'
> }
> async with httpx.AsyncClient() as client:
>     response = await client.get('<host>/v2/auth/session', headers=auth_headers)
> ```
>
> This will return a JWT token, which will include a `accessToken` field:
>
> ```json Session Response theme={null}
> {
>   "idToken": "...",
>   "accessToken": "<session_id>",
>   "refreshToken": "...",
>   "expiresIn": 3600,
>   "checksum": "..."
> }
> ```
>
> For our purposes, only `accessToken` is required. This token should be included in the iFrame URL as a query parameter:
>
> ```html iframe-integration.html theme={null}
> <iframe
>   src="https://ailsa.forestreet.com/path/to/page?sessionId=<session_id>"
>   width="100%"
>   height="600px"
>   frameborder="0"
> />
> ```
>
> Then all subsequent requests made within the iFrame will automatically include the session ID in the request headers,
> allowing Forestreet to authenticate the user without requiring them to log in again.
>
> > [!TIP]
> >
> > This method is suitable for: - iFrame integrations, or - applications where you need to give an unauthenticated user
> > access to Forestreet features for a limited duration, and that secret has to be exposed to the frontend.
>
> > [!WARNING]
> >
> > This method is **not suitable** for: - backend services or scripts, as the session may not live long enough for all
> > the subsequent requests to complete


# Get a company logo by domain
Source: https://docs.forestreet.com/api-reference/endpoints/assets/get-a-company-logo-by-domain

get /v2/assets/logos/{domain}
Attempts to retrieve a company logo by its domain. Cached logos are stored in MySQL for 90 days before they are refreshed via the logo.dev API.

  This endpoint supports both JSON and PNG responses.

  The path should contain the domain name.

  Example: google.com

  If the logo cannot be served and a PNG response is requested, a magnifying-glass fallback icon is returned.



# Get an iconographic symbol by name
Source: https://docs.forestreet.com/api-reference/endpoints/assets/get-an-iconographic-symbol-by-name

get /v2/assets/icons/{iconName}
Attempts to retrieve an iconographic symbol by its name from the Noun Project API.
    
    This endpoint supports both JSON and PNG responses.

    If the icon is not found and a PNG response is requested, it will return a fallback icon in form of
    a magnifying glass.



# Get session ID
Source: https://docs.forestreet.com/api-reference/endpoints/auth/get-session-id

get /v2/auth/session

  Create new session using a valid API key, which will return a JWT token in the response.

  This allows API users to create a timed session from the backend, before passing the resultant
  JWT token to an unauthenticated frontend application. This prevents any risks of the API key
  being exposed to the frontend application.

  <Tip>See also [the `PUT /v2/auth/session` endpoint](/api-reference/endpoints/auth/set-session-cookies).</Tip>
  



# Set Session Cookies
Source: https://docs.forestreet.com/api-reference/endpoints/auth/set-session-cookies

put /v2/auth/session

  Using a JWT token and a checksum, this endpoint sets session cookies in the user's browser.

  This is typically used in iFrames where a client's backend generates a JWT Token using its API key,
  and the backend then asks the end user's browser to render an iFrame with the JWT Token embedded.
  The iFrame then calls this endpoint to set the cookies in the browser.

  The checksum is computed using HMAC with the tokens as input to ensure the tokens have not been tampered with.
  If the checksum does not match, an error is thrown indicating that the tokens have been tampered with.

  <Tip>See also [the `GET /v2/auth/session` endpoint](/api-reference/endpoints/auth/get-session-id).</Tip>

  <Note>You can use this endpoint to set the cookies in the iFrame, then redirect the user to the desired page
  using the [`redirectUrl`](#body-redirect-url) parameter.</Note>
  



# Sign in
Source: https://docs.forestreet.com/api-reference/endpoints/auth/sign-in

post /v2/auth/sign-in

  Sign in a user with email and password; upon success, authentication cookies are set
  in the browser.

  This is used by Forestreet's internal frontend application.
  



# Sign out
Source: https://docs.forestreet.com/api-reference/endpoints/auth/sign-out

post /v2/auth/sign-out
Revoke the current bearer or cookie session and clear authentication cookies.



# Generate keywords for search
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/generate-keywords-for-search

post /v2/discovery/search-criteria/keywords
Generate AI-suggested keywords to improve your search criteria.

## Overview

This endpoint generates AI-suggested keywords to help refine and improve your search criteria for better discovery
results.

> [!NOTE]
>
> **Workflow Step**: This is an optional refinement step in Phase 1 of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-1-search-criteria-generation).

## Usage

Use this endpoint to enhance your search criteria with AI-suggested keywords:

* **Refinement**: Improve existing search criteria with better keywords
* **Discovery**: Find relevant terms you might have missed
* **Optimization**: Get more targeted and comprehensive search results

## Best Practices

> [!TIP]
>
> **Optional Step**: This endpoint is not required but can significantly improve your discovery results by suggesting
> relevant keywords you might not have considered.

> [!WARNING]
>
> **Important**: Review the suggested keywords carefully before using them in your discovery process. Not all
> suggestions may be relevant to your specific use case.


# Generate search criteria
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/generate-search-criteria

post /v2/discovery/search-criteria
Convert natural language queries into structured search criteria for AI-powered company discovery.

## Overview

This endpoint converts your natural language business question into structured search criteria that our AI algorithms
can use to discover relevant companies.

> [!NOTE]
>
> **Workflow Step**: This is Step 1 of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-1-search-criteria-generation).

## Usage

The endpoint accepts a simple search input and returns comprehensive search criteria including:

* **Market Classification**: Type, role, and geographic scope
* **Keyword Groups**: Features, users, synonyms, and irrelevant terms
* **Search Parameters**: Count limits, project type, and constraints

## Best Practices

> [!TIP]
>
> **Pro Tip**: Be specific in your search input. Instead of "AI companies", try "AI-powered transcription services for
> enterprise healthcare customers."

> [!WARNING]
>
> **Important**: The generated search criteria will be used in subsequent discovery steps. Take time to review and
> potentially refine the criteria before proceeding to company discovery.


# Get job status
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/get-job-status

get /v2/discovery/{marketId}/jobs
Retrieve the status and progress of discovery jobs for a given market, optionally filtered by job IDs and/or status.

## Overview

This endpoint allows you to monitor the progress of asynchronous jobs (including both discovery and publish jobs) for a
specific market. Use it to check which steps have completed and the current progress of each job.

> [!NOTE]
>
> **Workflow Step**: This endpoint is used throughout the [Market Research
> Workflow](/api-reference/guides/platform-discovery), including both discovery and publish phases.

## Usage

Call this endpoint with the `marketId` to get a list of all jobs and their statuses.

### Best Practices

> [!TIP]
>
> **Polling Strategy**: Check the status every 30-60 seconds


# Get search criteria
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/get-search-criteria

get /v2/discovery/{marketId}/search-criteria
Retrieve the search criteria used for a specific market discovery.

## Overview

This endpoint retrieves the search criteria that was used to discover companies for a specific market.

> [!NOTE]
>
> **Workflow Step**: This is part of Phase 3 (Company Review) of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-3-company-review-optional).

## Usage

Use this endpoint to review the search criteria that was used for discovery, which is helpful for:

* **Iteration**: Understanding what criteria led to the current results
* **Documentation**: Keeping track of search parameters used

## Best Practices

> [!TIP]
>
> **Review Process**: This endpoint is particularly useful during the company review phase to understand what criteria
> led to the discovered companies.

> [!WARNING]
>
> **Important**: This endpoint only works for markets that have completed the discovery process. Make sure discovery is
> finished before calling this endpoint.


# Get search criteria history
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/get-search-criteria-history

get /v2/discovery/{marketId}/search-criteria/history
Retrieve the history of search criteria iterations for a specific market.

## Overview

This endpoint retrieves the complete history of search criteria iterations that have been used for a specific market
discovery.

> [!NOTE]
>
> **Workflow Step**: This is part of Phase 3 (Company Review) of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-3-company-review-optional).

## Usage

Use this endpoint to track the evolution of search criteria for a market, which is helpful for:

* **Iteration**: See how search criteria evolved over time
* **Documentation**: Maintain a complete history of search parameters

## Best Practices

> [!TIP]
>
> **Iteration Process**: This endpoint is useful when you've refined your search criteria multiple times and want to
> track the progression.

> [!WARNING]
>
> **Important**: This endpoint only works for markets that have completed the discovery process. Make sure discovery is
> finished before calling this endpoint.


# Publish a market
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/publish-a-market

post /v2/discovery/{marketId}/publish
Publish discovered companies and trigger comprehensive market analysis and enrichment.

## Overview

This endpoint publishes your discovered companies and triggers comprehensive analysis including financial data, ESG
metrics, news analysis, and competitive insights.

> [!NOTE]
>
> **Workflow Step**: This is Step 4 of the [Discovery
> Workflow](/api-reference/guides/platform-discovery#phase-4-market-analysis--publishing).

> [!WARNING]
>
> Important: This is an asynchronous process that can take 45-60 minutes to complete. Use the status endpoint to monitor
> progress

## Usage

The endpoint accepts pipeline configuration options to control which analysis steps are performed:

* **Pipeline Choices**: Configure which analysis steps to run
* **Response**: Job IDs for monitoring the publishing process

> [!TIP]
>
> **Pipeline Configuration**: Choose analysis steps based on your research goals. Each step adds valuable insights but
> increases processing time.

## Pipeline Steps

The publishing process includes several analysis steps:

* **Reverse Geocoding**: Convert company addresses to geographic coordinates
* **DUNS Mapper**: Map companies to DUNS numbers for enhanced data
* **People**: Extract and analyse key personnel information
* **News**: Gather and analyse recent news and media coverage
* **ESG**: Collect Environmental, Social, and Governance data
* **Momentum Score**: Calculate market momentum and sentiment scores
* **Market Radar**: Generate competitive landscape analysis
* **Topic Analysis**: Identify key themes and topics in the market
* **Phrase Explorer**: Analyse market terminology and language patterns
* **Feature Map**: Generate visual feature maps for market insights
* **Publish Email**: Send notification emails upon completion

## Monitoring Progress

After starting the publishing process, you can monitor progress using the same status endpoint:

```bash theme={null}
GET /v2/markets/{marketId}/services/publish/status
```

## Accessing Published Data

Once publishing is complete, you can access your market data through various endpoints:

```bash theme={null}
  # Get companies in the market
  GET /v2/markets/12345/companies

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

## Best Practices

> [!TIP]
>
> **For Better Results**: - Ensure discovery is fully completed before publishing - Choose pipeline steps relevant to
> your research goals - Consider the review step for quality control

> [!WARNING]
>
> **Important Notes**: - Only one publishing process can run per market at a time - The process cannot be interrupted
> once started


# Start discovery for existing market
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/start-discovery-for-existing-market

post /v2/discovery/{marketId}/start
Add more companies to an existing market using AI-powered discovery process.



# Start discovery for new market
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/start-discovery-for-new-market

post /v2/discovery/start
Create a new market and initiate AI-powered company discovery process using structured search criteria.

## Overview

This endpoint triggers an asynchronous AI-powered process that discovers companies based on your search criteria.

> [!NOTE]
>
> **Workflow Step**: This is Step 2 of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-2-company-discovery).

> [!WARNING]
>
> **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

> [!TIP]
>
> **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](/api-reference/endpoints/discovery/get-discovery-job-status) endpoint:

```bash theme={null}
GET /v2/discovery/12345/status
```

> [!TIP]
>
> **Polling Strategy**: Check status every 30-60 seconds. The process typically takes 5-15 minutes depending on search
> complexity.

## Best Practices

> [!TIP]
>
> **For Better Results**: Use clear and specific search criteria generated from the&#x20;
> [Generate Search Criteria](/api-reference/endpoints/discovery/generate-search-criteria) endpoint.
> Well-defined criteria help the discovery process return more relevant companies.

> [!WARNING]
>
> **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.


# Update company review status
Source: https://docs.forestreet.com/api-reference/endpoints/discovery/update-company-review-status

patch /v2/discovery/{marketId}/companies/reviews
Update the review status of discovered companies for quality control.

## Overview

This endpoint allows you to approve, reject, or request more information about discovered companies during the review
phase.

> [!NOTE]
>
> **Workflow Step**: This is part of Phase 3 (Company Review) of the [Market Research
> Workflow](/api-reference/guides/platform-discovery#phase-3-company-review-optional).

## Usage

Use this endpoint to control which companies proceed to the final analysis phase:

* **Include**: Include companies that meet your criteria
* **Exclude**: Exclude companies that don't meet your criteria
* **Unreviewed**: Undo previous decisions and re-review companies

> [!TIP]
>
> **Quality Control**: This step is crucial for ensuring only relevant companies are included in your market analysis.

> [!WARNING]
>
> **Important**: This step is optional but recommended for quality control. Once you publish the market, the review
> phase is complete.


# Create a dossier
Source: https://docs.forestreet.com/api-reference/endpoints/dossier/create-a-dossier

post /v2/collections/{collectionId}/dossier/create
Create a new dossier in the specified collection using AI to generate supplier information



# Delete a dossier
Source: https://docs.forestreet.com/api-reference/endpoints/dossier/delete-a-dossier

delete /v2/collections/{collectionId}/dossier/{agentId}
Remove a dossier from the specified collection



# Get a dossier
Source: https://docs.forestreet.com/api-reference/endpoints/dossier/get-a-dossier

get /v2/collections/{collectionId}/dossier/{agentId}
Retrieve a specific dossier by agent ID and collection ID



# Get dossiers in collection
Source: https://docs.forestreet.com/api-reference/endpoints/dossier/get-dossiers-in-collection

post /v2/collections/{collectionId}/dossiers
Retrieve dossiers associated with a specific collection with optional filtering and pagination



# Update a dossier
Source: https://docs.forestreet.com/api-reference/endpoints/dossier/update-a-dossier

patch /v2/collections/{collectionId}/dossier/{agentId}
Update a dossier by adding it to another collection, moving it to another collection, or modifying its properties



# Get an Observation
Source: https://docs.forestreet.com/api-reference/endpoints/events-monitor/get-an-observation

get /v2/events-monitor/observation/{observationId}

  Retrieves a single observation based on the provided observation ID.

  <Info>
  **Subscription Endpoint**

  This endpoint has a special subscription requirement. Your API Key needs to be
  subscribed to this endpoint in order to access it; otherwise it will return a 403
  Forbidden error. Please contact Forestreet support to get subscribed.
  </Info>

  An Observation is a piece of information or data point that has been collected and
  stored in our system. It serves as the foundational unit of information to join
  together as Events, and can represent various types of data such as news articles,
  social media posts, analyst reports, or any other relevant information that we want to
  track and analyze. Each observation contains metadata about its source, content,
  publication time, and other relevant attributes that allow us to process and analyze
  it effectively.
  



# List events
Source: https://docs.forestreet.com/api-reference/endpoints/events-monitor/list-events

get /v2/events-monitor/events

  Retrieves a list of events based on the provided query parameters. Supports filtering
  by date range, taxonomy matches, impacted entity likelihood and severity scores,
  free-text search, and pagination. By default, only events with at least one impacted
  entity with likelihood 2-3 and severity 2-3 are returned. Score bounds are inclusive.
  Results are sorted by reference count descending, then by the highest
  likelihood * severity product among impacted entities matching the impactedEntity
  filter descending. If no impactedEntity filter is supplied, all impacted entities
  are considered for the secondary sort.
  If date bounds are omitted, the range defaults to the previous UTC day at 00:00
  through the current UTC day at 23:59.

  <Info>
  **Subscription Endpoint**

  This endpoint has a special subscription requirement. Your API Key needs to be
  subscribed to this endpoint in order to access it; otherwise it will return a 403
  Forbidden error. Please contact Forestreet support to get subscribed.
  </Info>

  An Event is a collection of one or more Observations that all refer to the same
  underlying occurrence. For example, if a company is acquired, there may be multiple
  news articles about the acquisition, and each article would be an Observation.
  However, all of these Observations would be grouped under a single Event that
  represents the acquisition itself.

  <Note>
  The grouping of Events is subjective to some extent; a different person may group
  Observations differently based on their interpretation. Our system uses a community
  detection algorithm on a graph of Observations linked up by proprietary heuristics to
  determine which Observations belong to the same Event. These may not always align
  with everyone's intuition, and we are continuously working to improve our algorithms
  and welcome user feedback on any misgroupings they observe.
  </Note>
  



# Get a company
Source: https://docs.forestreet.com/api-reference/endpoints/impact/get-a-company

get /v2/impact/companies/{identifier}
Get impact data for a specific company



# Get news for a company
Source: https://docs.forestreet.com/api-reference/endpoints/impact/get-news-for-a-company

get /v2/impact/companies/{identifier}/news
Get news for a specific company



# Search companies
Source: https://docs.forestreet.com/api-reference/endpoints/impact/search-companies

post /v2/impact/search
Search for impact data



# Delete a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/delete-a-market

delete /v2/markets/{marketId}
Delete a specific market in the collection



# Get a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-a-market

get /v2/markets/{marketId}
Fetch a specific market in the collection



# Get esg data for a company in a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-esg-data-for-a-company-in-a-market

get /v2/markets/{marketId}/companies/{domain}/esg



# Get esg data for a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-esg-data-for-a-market

post /v2/markets/{marketId}/esg



# Get esg filters for a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-esg-filters-for-a-market

post /v2/markets/{marketId}/esg/filters



# Get market explorer filters
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-market-explorer-filters

get /v2/markets/{marketId}/explorer/companies/filters
Fetches available filters for a specific market.
  
  [List Market Explorer Companies](./list-market-explorer-companies) supports in its
  Query parameters a set of filters that can be applied to the list of companies. This
  endpoint provides the available options for those filters, which can be used to
  construct the query for listing companies. In particular, these filters are extracted
  across all companies in the market without pagination, allowing UI applications to
  show all available filters regardless of the pagination applied on the UI.
  
  <Tip>Not typically useful for pure API consumers.</Tip>



# Get markets
Source: https://docs.forestreet.com/api-reference/endpoints/markets/get-markets

get /v2/collections/{collectionId}/markets
Fetch list of markets in the collection with pagination and filtering



# List market explorer companies
Source: https://docs.forestreet.com/api-reference/endpoints/markets/list-market-explorer-companies

get /v2/markets/{marketId}/explorer/companies
List the companies in a published market, intended for Market Explorer use. 
    Differs from a draft study by having company metadata populated, and having completed a detailed scrape.



# Move a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/move-a-market

post /v2/markets/{marketId}/move
Move a specific market in the collection



# Update a market
Source: https://docs.forestreet.com/api-reference/endpoints/markets/update-a-market

patch /v2/markets/{marketId}
Update a specific market in the collection



# Retrieve cached company logo by domain (public)
Source: https://docs.forestreet.com/api-reference/endpoints/public/retrieve-cached-company-logo-by-domain-public

get /v2/public/assets/logos/{domain}
Serves company logos cached within the past 90 days. This endpoint is only used for companies discovered on the Forestreet platform; it does not actively search for as-yet-unknown company logos. If the requested logo is missing and a PNG response is requested, a magnifying-glass fallback icon is returned.

This endpoint is not authenticated. It is useful for custom UI serving Forestreet data, where the client's browser does not have a Forestreet login session.



# Create a collection
Source: https://docs.forestreet.com/api-reference/endpoints/teams/create-a-collection

post /v2/teams/{teamId}/collections

  Create a collection within a specific team.

  The authenticated user must have access to the team.
  



# Create a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/create-a-team

post /v2/teams

  Creates a new team with the provided details.

  If no team admin is specified, the user making the request will be set as the team admin by default.

  <Warning>
  **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.
  If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.

  We do not provide external support for this endpoint unless permissions had been negotiated in your contract.
  </Warning>
  



# Delete a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/delete-a-team

delete /v2/teams/{teamId}

  Delete the specified team.

  <Warning>
  **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.
  If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.

  We do not provide external support for this endpoint unless permissions had been negotiated in your contract.
  </Warning>
  



# Delete export endpoint for a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/delete-export-endpoint-for-a-team

delete /v2/teams/{teamId}/endpoint/{endpointName}

  Delete an existing Export Via API endpoint for a team.
  



# Edit a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/edit-a-team

patch /v2/teams/{teamId}

  Edits a team with the provided details.

  <Warning>
  **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.
  If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.

  We do not provide external support for this endpoint unless permissions had been negotiated in your contract.
  </Warning>
  



# Get a team by ID
Source: https://docs.forestreet.com/api-reference/endpoints/teams/get-a-team-by-id

get /v2/teams/{teamId}
Fetch the details of a specific team by its ID.



# Get current user's teams
Source: https://docs.forestreet.com/api-reference/endpoints/teams/get-current-users-teams

get /v2/teams
Fetch the teams associated with the current user



# Get team collections
Source: https://docs.forestreet.com/api-reference/endpoints/teams/get-team-collections

get /v2/teams/{teamId}/collections
Fetch the collections associated with a specific team



# Get team export endpoints
Source: https://docs.forestreet.com/api-reference/endpoints/teams/get-team-export-endpoints

get /v2/teams/{teamId}/endpoints
Fetch the Export Via API endpoints associated with a specific team



# Get team export endpoints, advanced
Source: https://docs.forestreet.com/api-reference/endpoints/teams/get-team-export-endpoints-advanced

post /v2/teams/{teamId}/endpoints
Fetch the Export Via API endpoints associated with a specific team



# Register export endpoint for a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/register-export-endpoint-for-a-team

put /v2/teams/{teamId}/endpoint/{endpointName}

  Register a new Export Via API endpoint for a team.
  



# Update export endpoint for a team
Source: https://docs.forestreet.com/api-reference/endpoints/teams/update-export-endpoint-for-a-team

patch /v2/teams/{teamId}/endpoint/{endpointName}

  Update an existing Export Via API endpoint for a team.
  



# About me
Source: https://docs.forestreet.com/api-reference/endpoints/users/about-me

get /v2/users/me

  Get the current user's information and their access to teams and collections.

  This endpoint returns the user's authentication metadata, including their ID and email,
  as well as the IDs of teams and collections they have access to.
  



# Export via API
Source: https://docs.forestreet.com/api-reference/guides/export-api

Connect a market to your internal system using an API hook.

> [!TIP]
>
> This section is about an ***client supplied*** endpoint that Forestreet platform
> will send a `POST` request to.
>
> The **Request** section describes the body of the `POST` request that will be
> sent to your API, and the **Response** section describes the expected response
> from your API.

Forestreet Platform allows users to initiate an API call to export a market to their internal system. This feature is
useful for users with real time data integration requirements, without the need for exporting and importing data
manually.

The workflow is as follows:

**1. Register Endpoint**

Each team will be able to register a number of endpoints with Forestreet.

All endpoints must be `POST` endpoints, and must be able to accept a JSON body.

> [!NOTE]
>
> Refer to the [Register Endpoint](#to-register-an-endpoint)
> section below for the details of the endpoint registration.

**2. User create studies**

Users in your Team shall use the Forestreet platform to create markets and
publish them as required.

Using the Market Collection feature, users can group markets together for different
projects or sub-teams etc.

**3. Export to API**

After publishing a market, users can select the market and choose to export it
via the **Export to API** feature:

![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/export-api.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=f3d3c44001d4a6cfccfa477326a80b73)

This will be visible if API endpoints are registered for the team.

**4. Choose the endpoint**

All the registered endpoints for the Team will be displayed in a dropdown list, and
the user can select the desired endpoint to export the market to.

The description will be displayed to the user to help them choose the correct endpoint,
and the user can click on the **Export** button to initiate the API call.

> [!NOTE]
>
> See the [**Request Body sent to your API**](#post-body-to-your-api) section for the expected body of the `POST` request.

**5. Choose companies**

The user have 3 possible set of companies to export:

* **Export all companies**: All companies in this market will be exported.
* **Export filtered companies**: Only companies that are currently visible to the user on the Market Explorer will be exported.
  This takes into account filters and pagination applied by the user.
  > [!TIP]
  >
  > This implies that the maximum number of companies exportable will be the selected
  > page size of the Market Explorer.
* **Export only selected companies**: When this option is selected, a list of companies will be shown
  to the user, and they can select the companies they want to export.

**6. Endpoint Response**

Depending on the Status Code returned by your API, the user will be shown a success
or failure message.

> **Success**
>
> If successful, the user will be shown a title and message that you provide.
>
> If a redirect URL is provided, the user will be redirected to that URL after 5 seconds.

> **Failure**
>
> If your API returns a `400`-`499` status code **or a `207`**, the user will be shown a title, message,
> and - optionally - a list of references. Each reference must include a `title`; `message`, `url`, and `type`
> (`ok` | `info` | `warning` | `error`, default `warning`) are optional. The UI renders references as
> collapsible rows with icons (✅/ℹ️/⚠️/🚫), supports long lists with scrolling, and only expands when `message` or `url` is present.

> **Error**
>
> If your API does not respond within 15 seconds, or the connection was closed, or
> the return status code was `500`-`599`, we will try again for a maximum of 3 times.
> The user will be shown a generic error message, referring them to contact their IT support.

### To Register an Endpoint

Endpoints are attached to a Team, and can be registered via the "Manage Teams" feature.

**1. Register Endpoint**

To register an endpoint, you must be a Team Admin or have the appropriate permissions
to manage teams.

![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/team-selection.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=06b1f89d2e15737ba67e3cc8b0ba0de1)

Settings Tab

**2. Navigate to Manage Teams**

Navigate to the **Manage Teams** section in the Forestreet platform.

![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/list-of-endpoints.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=50d30d7a6241beb19b00fa81ab91b157)

API Endpoints Section

**3. API Endpoints Section**

In the **API Endpoints** section, you can view existing endpoints and register new ones.

**4. Register Endpoint Form**

Click on the **Register Endpoint** button and fill in the required details.

![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/register-endpoint.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=08f51f97c56cbeea70a7ce6cfa190e8b)

Register Endpoint Form

> [!NOTE]
>
> The name of the endpoint must be unique within the Team, and cannot be changed
> after it has been registered. If you need to change the name, you must delete the
> endpoint and register a new one with the desired name.

**5. Submit the Form**

After filling in the details, click on the **Register** button to save the endpoint.

> **Endpoint metadata**
>
> Each endpoint can be registered with the following details:
>
> **name** `string` *required*
>
> A unique name for the endpoint that will be displayed to the user.
>
> > [!TIP]
> >
> > The maximum allowed length is 255 characters.
>
> **url** `string` *required*
>
> A valid URL that Forestreet can send a `POST` request to.
>
> This can include any path, query parameters, or headers that your API requires.
>
> This URL must be accessible from the internet, and must not require any special
> authentication or headers to be sent by Forestreet.
>
> ```URL Example theme={null}
> https://your-internal-system.com/api/v1/forestreet-export?teamId=1234&userEmail={user.email}
> ```
>
> The following placeholder variables can be used:
>
> | Variable | Description |
> | - | - |
> | `user.name` | The full name of the user who initiated the export. |
> | `user.email` | The email address of the user who initiated the export. |
>
> These placeholder variables will be resolved at the point of export by Forestreet.
>
> > [!TIP]
> >
> > The maximum allowed length is 1,024 characters.
>
> **description** `string` *required*
>
> A one-line description of the endpoint that will be displayed to the user.
>
> > [!TIP]
> >
> > The maximum allowed length is 1,024 characters.
>
> **headers** `object`
>
> A JSON object containing any headers that your API requires.
>
> These headers will be sent with every request to this endpoint, and is useful
> for any authentication or API keys that your API requires.
>
> A minimum set of headers will be sent regardless of what is provided. **These
> cannot be overridden.**:
>
> * `Content-Type`: always `application/json`
> * `Idempotency-Key`: a UUID that is unique for each request. Upon error, all
>   retry requests will use the same `Idempotency-Key`.
>
> ```JSON Example Headers theme={null}
> {
>     "X-Api-Key": "your-api-key"
> }
> ```

## `POST` Body to your API

After the user had chosen the endpoint and clicked on the **Export** button, Forestreet will send a `POST` request to
the URL provided in the endpoint registration.

An example body of the `POST` request is shown on the right, to illustrate the structure of the data that will be sent
to your API.

> [!NOTE]
>
> Unfortunately we cannot provide any IP ranges for whitelisting, as our servers could be run globally from all AWS
> regions.

This is equivalent to the [Response](/api-reference/market/companies/companies#response) from the Companies endpoint,
with the following `fields` selected:

```JSON Equivalent Companies Request theme={null}
{
    "page": 1,
    "itemsPerPage": 500,
    "sorts": {
        "score": "desc"
    },
    "fields": [
        "domain",
        "score",
        "name",
        "description",
        "overallMomentum",
        "contactNumber",
        "contactEmail",
        "actualRevenue",
        "naics",
        "operatesIn",
        "dunsNumbers"
    ]
}
```

> [!TIP]
>
> The maximum number of companies that will be sent is 500. If more companies are required, use the `market.id` to query
> the [Market/Companies](/api-reference/market/companies/companies) endpoint for paginated results.

```JSON Request Body sent to your API theme={null}
{
    "meta": {
        "totalItems": 3
    },
    "market": {
        "id": 2,
        "name": "Transcription Services"
    },
    "data": [
        {
            "domain": "ibm.com",
            "name": "IBM",
            "description": "International Business Machines Corporation (IBM) provides computer solutions. The Company offers application, technology consulting and support, process design and operations, cloud, digital workplace, and network services, as well as business resiliency, strategy, and design solutions. IBM serves clients worldwide.",
            "overallMomentum": 48,
            "contactNumber": "+1 914-499-1900",
            "contactEmail": "ews@us.ibm.com",
            "actualRevenue": 60530000000,
            "naics": [
                {
                    "code": "518210",
                    "name": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services",
                    "level": 4,
                    "isPrimary": true
                },
                {
                    "code": "518200",
                    "name": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services",
                    "level": 3,
                    "isPrimary": true
                },
                {
                    "code": "518000",
                    "name": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services",
                    "level": 2,
                    "isPrimary": true
                },
                {
                    "code": "510000",
                    "name": "Information",
                    "level": 1,
                    "isPrimary": true
                },
                {
                    "code": "334111",
                    "name": "Electronic Computer Manufacturing",
                    "level": 5,
                    "isPrimary": false
                },
                {
                    "code": "334112",
                    "name": "Computer Storage Device Manufacturing",
                    "level": 5,
                    "isPrimary": false
                },
                {
                    "code": "335000",
                    "name": "Electrical Equipment, Appliance, and Component Manufacturing",
                    "level": 2,
                    "isPrimary": false
                },
                {
                    "code": "334419",
                    "name": "Other Electronic Component Manufacturing",
                    "level": 5,
                    "isPrimary": false
                },
                {
                    "code": "330000",
                    "name": "Manufacturing",
                    "level": 1,
                    "isPrimary": false
                },
                {
                    "code": "541618",
                    "name": "Other Management Consulting Services",
                    "level": 5,
                    "isPrimary": false
                },
                {
                    "code": "541610",
                    "name": "Management Consulting Services",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "334410",
                    "name": "Semiconductor and Other Electronic Component Manufacturing",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "541600",
                    "name": "Management, Scientific, and Technical Consulting Services",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "334400",
                    "name": "Semiconductor and Other Electronic Component Manufacturing",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "541000",
                    "name": "Professional, Scientific, and Technical Services",
                    "level": 2,
                    "isPrimary": false
                },
                {
                    "code": "540000",
                    "name": "Professional, Scientific, and Technical Services",
                    "level": 1,
                    "isPrimary": false
                },
                {
                    "code": "334110",
                    "name": "Computer and Peripheral Equipment Manufacturing",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "334100",
                    "name": "Computer and Peripheral Equipment Manufacturing",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "334000",
                    "name": "Computer and Electronic Product Manufacturing",
                    "level": 2,
                    "isPrimary": false
                },
                {
                    "code": "513210",
                    "name": "Software Publishers",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "513200",
                    "name": "Software Publishers",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "513000",
                    "name": "Publishing Industries",
                    "level": 2,
                    "isPrimary": false
                }
            ],
            "operatesIn": ["us", "ca", "gb", "de", "fr", "in", "jp", "br", "au", "mx", "cn", "it", "es", "nl", "kr", "ch", "se", "sg", "ae", "za"],
            "dunsNumbers": ["123456789"]
        },
        {
            "domain": "pindrop.com",
            "name": "Pindrop",
            "description": "Pindrop Security, Inc. develops and markets security software. The Company offers a caller identification product that helps detect, report, and mitigate phone frauds. Pindrop Security serves the finance and banking industry in the United States.",
            "overallMomentum": 59,
            "contactNumber": "+1 866-245-4045",
            "contactEmail": "info@pindrop.com",
            "actualRevenue": 49000000,
            "naics": [
                {
                    "code": "541511",
                    "name": "Custom Computer Programming Services",
                    "level": 5,
                    "isPrimary": true
                },
                {
                    "code": "541510",
                    "name": "Computer Systems Design and Related Services",
                    "level": 4,
                    "isPrimary": true
                },
                {
                    "code": "541500",
                    "name": "Computer Systems Design and Related Services",
                    "level": 3,
                    "isPrimary": true
                },
                {
                    "code": "541000",
                    "name": "Professional, Scientific, and Technical Services",
                    "level": 2,
                    "isPrimary": true
                },
                {
                    "code": "540000",
                    "name": "Professional, Scientific, and Technical Services",
                    "level": 1,
                    "isPrimary": true
                },
                {
                    "code": "561612",
                    "name": "Security Guards and Patrol Services",
                    "level": 5,
                    "isPrimary": false
                },
                {
                    "code": "561610",
                    "name": "Investigation, Guard, and Armored Car Services",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "561600",
                    "name": "Investigation and Security Services",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "561000",
                    "name": "Administrative and Support Services",
                    "level": 2,
                    "isPrimary": false
                },
                {
                    "code": "560000",
                    "name": "Administrative and Support and Waste Management and Remediation Services",
                    "level": 1,
                    "isPrimary": false
                },
                {
                    "code": "513210",
                    "name": "Software Publishers",
                    "level": 4,
                    "isPrimary": false
                },
                {
                    "code": "513200",
                    "name": "Software Publishers",
                    "level": 3,
                    "isPrimary": false
                },
                {
                    "code": "513000",
                    "name": "Publishing Industries",
                    "level": 2,
                    "isPrimary": false
                },
                {
                    "code": "510000",
                    "name": "Information",
                    "level": 1,
                    "isPrimary": false
                }
            ],
            "operatesIn": ["gb", "us"],
            "dunsNumbers": ["987654321"]
        },
        {
            "domain": "talkatoo.com",
            "name": "Talkatoo",
            "description": "Talkatoo makes and sells dictation software for professionals.Our customers are busy professionals - doctors, veterinarians, and lawyers - who have high hourly bill rates and hectic schedules; their time is valuable. Driven by liability management and professional regulation, their documentation req... Read more",
            "overallMomentum": 29,
            "contactNumber": null,
            "contactEmail": null,
            "actualRevenue": 7000000,
            "naics": [
                {
                    "code": "513210",
                    "name": "Software Publishers",
                    "level": 4,
                    "isPrimary": true
                },
                {
                    "code": "513200",
                    "name": "Software Publishers",
                    "level": 3,
                    "isPrimary": true
                },
                {
                    "code": "513000",
                    "name": "Publishing Industries",
                    "level": 2,
                    "isPrimary": true
                },
                {
                    "code": "510000",
                    "name": "Information",
                    "level": 1,
                    "isPrimary": true
                }
            ],
            "operatesIn": ["ca"],
            "dunsNumbers": ["456789123"]
        }
    ]
}
```

```TEXT Minimum Headers theme={null}
Content-Type: application/json
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
```

## Expected Response from your API

Your API should be constructed to return a JSON object with the following structure:

```JSON On Success theme={null}
{
    "title": "A title to display to the user",
    "message": "A block of text to be displayed to the user, explaining the action had been successful.<br/><br/>If the user is to be redirected, explain where they will be redirected to, and instructions to proceed.",
    "redirectUrl": "https://your-internal-system.com/redirect-url"
}
```

```JSON On Failure theme={null}
{
    "title": "A title to display to the user",
    "message": "A block of text to be displayed to the user, enclosed in a <pre> tag.",
    "references": [
        {
            "title": "Error Code 123",
            "message": "Detailed explanation of the error",
            "url": "https://your-internal-system.com/docs/error-codes/123",
            "type": "error"
        },
        {
            "title": "Contact IT Support",
            "url": "https://your-internal-system.com/it/contact",
            "type": "info"
        },
        {
            "title": "Simple reference without URL or message"
        }
    ]
}
```

#### On Success

Response status must be `200`, with `Content-Type: application/json` in the header, and a JSON body with the following
schema:

```JSON On Success theme={null}
{
    "title": "A title to display to the user",
    "message": "A block of text to be displayed to the user, explaining the action had been successful.<br/><br/>If the user is to be redirected, explain where they will be redirected to, and instructions to proceed.",
    "redirectUrl": "https://your-internal-system.com/redirect-url"
}
```

> [!NOTE]
>
> The above response will be rendered in a modal dialog to the user as:&#x20;
>
> ![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/export-success.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=e366cc9f036c368dfae966043b7cce8e)

If the `redirectUrl` is provided and is not `null`, the user will be redirected to that URL in a new window after 5
seconds.

#### On Failure

Response status code `400`-`499` **or `207` (Multi-Status)** will be considered a failure. Where possible, the response
body should contain a JSON object with the following schema:

```JSON On Failure theme={null}
{
    "title": "A title to display to the user",
    "message": "A block of text to be displayed to the user, informing them all the issues that occurred during the export, and links to documentations that help resolve them.",
    "references": [
        {
            "title": "Error Code 123",
            "message": "Detailed explanation of the error (optional)",
            "url": "https://your-internal-system.com/docs/error-codes/123",
            "type": "error"
        },
        {
            "title": "Contact IT Support",
            "url": "https://your-internal-system.com/it/contact",
            "type": "info"
        },
        {
            "title": "Simple reference (only title required)",
            "type": "warning"
        }
    ]
}
```

**Reference Object Fields:**

* `title` (required): The title of the reference item
* `message` (optional): Additional details about the reference
* `url` (optional): A clickable URL for more information
* `type` (optional): Visual indicator type - `ok` | `info` | `warning` | `error` (defaults to `warning`)

The UI will render references as collapsible rows with appropriate icons (✅/ℹ️/⚠️/🚫), support scrolling for long
lists, and only expand when `message` or `url` is present.

> [!NOTE]
>
> The above response will be rendered in a modal dialog to the user as:&#x20;
>
> ![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/export-failure.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=0dab42e5f655bbcb53beaaf7a640c4db)

#### On Exception/Timeout

Response status code `500`-`599` will be considered an server side exception. The API will try again immediately upto 3
times using the **same `Idempotency-Key`**.

If that fails, the user will be shown a generic error message, referring them to contact their IT support.

> [!NOTE]
>
> The response contents from your API will not be parsed regardless of `Content-Type` if the status code is an
> Exception.

> [!NOTE]
>
> An error message that describes the issue will be shown to the user in a human language.
>
> ![](https://mintcdn.com/forestreet/pahclZuClwwwBpfa/api-reference/guides/img/export-error.png?fit=max\&auto=format\&n=pahclZuClwwwBpfa\&q=85\&s=1def4729c05fce9bbd66ea86d413e1bf)


# iFrame Integration
Source: https://docs.forestreet.com/api-reference/guides/iframe-integration

Integrate Forestreet into your internal applications using an iFrame.

Forestreet can be integrated into your internal applications using an iFrame. This allows you to use Forestreet's
features within your existing applications without needing to build a separate UI.

An iFrame integration is possible with the following steps:

**1. Create a login session with your API Key**

Your application backend should call
the [`GET /v2/auth/session`](/api-reference/endpoints/auth/get-session-id) endpoint to create a timed session with your API Key. This
will return a session ID token.

> [!WARNING]
>
> Do not perform this step on the client-side, as it exposes your API Key. Always ensure that this step is performed securely on the server-side.**Forestreet reserves the right to revoke API Keys that are suspected to have leaked.**

**2. Embed the iFrame**

Your application backend then
embeds an iFrame in your application frontend, with the Session ID appended to the URL
as a query parameter. The URL should look like this:

```html iframe-integration.html theme={null}
<iframe
  src="https://ailsa.forestreet.com/path/to/page?sessionId=<session_id>"
  width="100%"
  height="600px"
  frameborder="0"
/>
```

**3. Use the iFrame**

The iFrame will load the Forestreet application, using the timed session
to authenticate the user. Authentications for any subsequent requests within the iFrame will be
handled automatically by Forestreet's frontend.

# Pages suitable for iFrame integration

These are common pages that can be embedded in an iFrame:

* [Supplier Dossier](/api-reference/ui-components/supplier-dossier)


# Discovery Workflow
Source: https://docs.forestreet.com/api-reference/guides/platform-discovery

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.

## 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

**Step 1**

## 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."

### 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.

**Step 2**

## 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 `skipDiscoveryReview` to `true` in `pipelineChoices`, the workflow will skip the company review phase and jump directly to **Phase 5: Market Analysis**.

```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.

### 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.

**Step 3**

## 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.

### 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.

### 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 4**

## 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.

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 5**

## 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

```

### 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

### 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

## 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.


# Introduction
Source: https://docs.forestreet.com/api-reference/introduction

Welcome to the home of the Forestreet API documentation.

![Hero Light](https://mintcdn.com/forestreet/bIVkQ4GpCRS8XyuT/images/hero.svg?fit=max\&auto=format\&n=bIVkQ4GpCRS8XyuT\&q=85\&s=c738daa06b8414c5538a8edab9c5a840)

## Overview

The Forestreet API offers a comprehensive suite of data retrieval for market insights and companies within a market.
Here's an overview of some of the data Forestreet provides:

* Real-time market discovery, or a selection of pre-built markets.
* The companies within those markets.
* Detailed company profiles including financials, ownership and shareholder, competitors, momentum scores, and services
  and features provided within that market.
* Environmental, Social, and Governance (ESG) metrics related to companies.
* Latest news and events at a market and individual company level.

With the Forestreet API, you will gain access to a rich set of market and company data, making it simple to derive
market insights.

To try a sample endpoint, choose one from the list to the left-hand side.

## Versioning

The current Forestreet API version is `v2`. This is accessible via the base URL:

```
https://rest.forestreet.com/v2/
```

This documentation is for this version of the API.

There is maintenance support for the previous version `v1` under the base URL:

```
https://api.forestreet.com/
```

If you are an existing client having integrated with the `v1` API before August 2025, you can find the documentation for
`v1` in the [Deprecated API section](/api-reference/deprecated/v1/index).


# Feature Map
Source: https://docs.forestreet.com/api-reference/ui-components/feature-map

An innovative data visualisation tool designed to provide a comprehensive overview of the features and services offered by companies within a market.

## Example: 'Transcription Services' Market

[https://ailsa.forestreet.com/embed/feature-map/2](https://ailsa.forestreet.com/embed/feature-map/2)

### Introduction

The Feature Map is a high-level data visualisation tool designed to provide an at-a-glance view of the range of features
and services offered by companies within a specific market. It employs a colour-coded approach, with darker hues
indicating features that are more widely provided by companies in the study. This intuitive widget is an essential asset
for market analysis and competitive research.

## Benefits

* Enhanced Market Insights: The Feature Map offers a clear and concise visual representation of market trends, enabling
  users to quickly identify which services and features are most common or lacking in the industry.

* Competitive Analysis: (When used within the Forestreet Platform) By highlighting the prevalence of different features
  among competitors, it aids businesses in understanding their competitive position and identifying potential areas for
  innovation or improvement.

* User-Friendly Interface: Designed for ease of use, the Feature Map presents complex data in an accessible format,
  making it suitable for both experts and those new to market analysis.

## Using In Your Own Web-pages / Web-apps

The Forestreet Feature Map is simple to use and embed in any webpage or webapp.

Simply copy and paste the HTML snippet below, providing a marketId at the end of the src URL. You can provide any
marketId found within the Forestreet database. Markets can be searched using the Search Market endpoint.

```html theme={null}
<iframe width="1024px" height="{600}" src="https://ailsa.forestreet.com/embed/feature-map/{marketId}" />
```


# About UI Components
Source: https://docs.forestreet.com/api-reference/ui-components/index

An assortment of ready-to-use UI components designed to enrich data visualisation and market analysis capabilities.

## Introduction

Enhance your web application with our suite of pre-built UI components. Each component is designed to integrate
seamlessly, offering rich insights into market dynamics and company performance. Whether you're looking to understand
competitive standings with the Momentum Score, visualise market feature saturation with the Feature Map, or explore the
diversity of discussion with the Topic Mosaic, our tools provide the clarity and depth you need.

* [**Feature Map**](/api-reference/ui-components/feature-map): A colour-coded visual tool that shows the distribution
  and prevalence of market features and services.
* [**Topic Mosaic**](/api-reference/ui-components/mosaic): A detailed display of the range and spread of conversations
  or topics within a market.
* [**Momentum Score**](/api-reference/ui-components/momentum-score): A composite visual representation of a company's
  market performance across various indicators.


# Momentum Score
Source: https://docs.forestreet.com/api-reference/ui-components/momentum-score

The Momentum Score widget is a holistic measure of a company's market performance, encapsulating key growth indicators in a single, intuitive visualisation.

## Example: Otter.ai within the Transcription Services Market

[https://ailsa.forestreet.com/embed/momentum/2/otter.ai](https://ailsa.forestreet.com/embed/momentum/2/otter.ai)

### Introduction

The Momentum Score widget is a dynamic data visualisation tool that measures and displays the performance momentum of a
company within a specific market. It aggregates various performance indicators such as web traffic, media coverage,
media sentiment, revenue estimates, and funding over a period (for instance, the last four years) into a single,
composite score. This score is visually represented in a radar or spider chart, allowing for an intuitive understanding
of the company's market position and growth trajectory.

The darker fill within the chart indicates higher scores in the respective domains, and the overall score is usually
presented as a number, signifying the company's combined performance strength. The Momentum Score is a crucial tool for
investors, analysts, and business leaders who require a quick yet comprehensive view of a company's trajectory and
market influence.

## Benefits

* Strategic Insight: The Momentum Score offers critical insights into a company's growth and market influence, allowing
  stakeholders to make informed strategic decisions.

* Competitive Benchmarking: It provides a benchmark against competitors, highlighting areas of strength and
  opportunities for improvement.

* Trend Analysis: The tool aids in identifying trends over time, offering a clear view of how a company's market
  position evolves in response to internal and external factors.

## Using In Your Own Web-pages / Web-apps

The Forestreet Momentum Score widget is simple to use and embed in any webpage or webapp.

Simply copy and paste the HTML snippet below, providing a marketId at the end of the src URL. You can provide any
marketId found within the Forestreet database. Markets can be searched using the Search Market endpoint.

```html theme={null}
// e.g: https://ailsa.forestreet.com/embed/momentum/2/otter.ai
<iframe width="100%" height="{600}" src="https://ailsa.forestreet.com/embed/momentum/{marketId}/{companyDomain}" />
```


# Supplier Dossier
Source: https://docs.forestreet.com/api-reference/ui-components/supplier-dossier

A comprehensive overview of a supplier's information, including their capabilities, competitors and market landscape.

A Supplier Dossier is a detailed report that provides a comprehensive overview of a supplier's information as well as
the market landscape in which they operate.

It contains 3 main sections:

* **Company Profile**: Company details, corporate structure, SWOT analysis and more.
* **Latest**: Latest news, sentiment analysis, and summary of recent events.
* **Market Insights**: The Market landscape in which the supplier operates, including market size, Porter's Five Forces
  analysis, and more.

## Retrieving a Supplier Dossier

Typically, dossiers are viewed on our [Supplier Dossier platform](https://dossier.forestreet.com/), but you can also
retrieve them programmatically using our API in order to integrate them into your own applications:

**1. List Dossiers**

With the [`GET
    /v2/collections/{collectionId}/dossiers/`](/api-reference/endpoints/dossier/get-dossiers-in-collection)
endpoint, you can retrieve a list of dossiers in a collection.

> **Listing dossiers by collection**
>
> ```sh Shell theme={null}
> curl -X GET '<host>/v2/collections/{collectionId}/dossiers/' \
> -H 'x-api-key: <api_token>'
> ```
>
> ```javascript Javascript Fetch theme={null}
> import { fetch } from "node-fetch";
>
> const response = await fetch("<host>/v2/collections/{collectionId}/dossiers/", {
>   method: "GET",
>   headers: {
>     "x-api-key": "<api_token>",
>   },
> });
> ```
>
> ```javascript Javascript Axios theme={null}
> import axios from "axios";
>
> const response = await axios.get("<host>/v2/collections/{collectionId}/dossiers/", {
>   headers: {
>     "x-api-key": "<api_token>",
>   },
> });
> ```
>
> ```python Python Blocking theme={null}
> import requests
> response = requests.get('<host>/v2/collections/{collectionId}/dossiers/', headers={
>     'x-api-key': '<api_token>'
> })
> ```
>
> ```python Python Async theme={null}
> import httpx
> async with httpx.AsyncClient() as client:
>     response = await client.get('<host>/v2/collections/{collectionId}/dossiers/', headers={
>         'x-api-key': '<api_token>'
>     })
> ```
>
> The response will contain a list of dossiers, each with its ID and other metadata:
>
> ```json Dossier List Response theme={null}
> {
>     "metadata": {
>         "pagination": {
>             "totalItems": 1,
>             "totalPages": 1,
>             "currentPage": 1,
>             "pageSize": 10
>         },
>         "filters": {},
>         "sort": [
>             {
>                 "field": "createdAt",
>                 "order": "desc"
>             }
>         ]
>     },
>     "data": [
>         {
>             "agentId": "06cc42ffec804a45bbe0389aab5beeda7a4ca0add2ab67cbe643203f803f3045",
>             "query": "SpaceX",
>             "agentType": "supplierDossier",
>             "createdBy": "02c6ce75-f2e1-4ce2-b3f7-29159d9ce9d9",
>             "createdAt": "2025-07-18T14:18:51.000Z",
>             "lastModifiedAt": null,
>             "lastTaskId": "c91d6d75-f553-453c-b101-13f47f681cf1",
>             "lastTaskStatus": {
>                 "taskId": "c91d6d75-f553-453c-b101-13f47f681cf1",
>                 "createdAt": "2025-07-18T14:18:51.000Z",
>                 "success": true,
>                 "status": "COMPLETED",
>                 "lastReportedAt": "2025-07-18T14:37:34.000Z",
>                 "lastReportedBy": "python-llm-agent-deployment-dev-86c9664c49-x5s6h"
>             }
>         }
>     ]
> }
> ```

**2. Check status of a dossier**

Since the dossiers takes some time to generate, you may want to check that the dossier is ready before displaying it to the user.

You can do this by checking the `lastTaskStatus` field in the dossier response. If the status is `COMPLETED`, then the
dossier is ready to be viewed.

**3. Displaying the dossier**

You can either

* display the dossier with your own UI component using the raw data, or
* embed our pre-built UI components in an iFrame.

**Retrieve the dossier by ID**

You can retrieve a dossier using the
[`GET /v2/collections/{collectionId}/dossiers/{agentId}`](/api-reference/endpoints/dossier/get-a-dossier) endpoint:

> **Retrieving a dossier by ID**
>
> The `agentId` is the unique identifier for the dossier, which you can get from the list of dossiers.
>
> Each dossier data structure has the field `agentId` which can be used below.
>
> ```sh Shell theme={null}
> curl -X GET '<host>/v2/collections/{collectionId}/dossier/{agentId}' \
> -H 'x-api-key: <api_token>'
> ```
>
> ```javascript Javascript Fetch theme={null}
> import { fetch } from 'node-fetch';
> const response = await fetch('<host>/v2/collections/{collectionId}/dossier/{agentId}', {
>     method: 'GET',
>     headers: {
>         'x-api-key': '<api_token>'
>     }
> });
> ```
>
> ```javascript Javascript Axios theme={null}
> import axios from 'axios';
> const response = await axios.get('<host>/v2/collections/{collectionId}/dossier/{agentId}', {
>     headers: {
>         'x-api-key': '<api_token>'
>     }
> });
> ```
>
> ```python Python Blocking theme={null}
> import requests
> response = requests.get('<host>/v2/collections/{collectionId}/dossier/{agentId}', headers={
>     'x-api-key': '<api_token>'
> })
> ```
>
> ```python Python Async theme={null}
> import httpx
> async with httpx.AsyncClient() as client:
>     response = await client.get('<host>/v2/collections/{collectionId}/dossier/{agentId}', headers={
>         'x-api-key': '<api_token>'
>     })
> ```
>
> > [!TIP]
> >
> > See [the dossier endpoint](/api-reference/endpoints/dossier/get-a-dossier) for more details on the dossier structure.

**Embed our UI components**

You can embed our pre-built UI components in an iFrame by using [Session ID](/api-reference/authentication). For details,
see the [iFrame integration guide](/api-reference/guides/iframe-integration).

```html iFrame theme={null}
<iframe
    src="https://dossier-staging.forestreet.com/teams/{teamId}/collections/{collectionId}/dossier/{agentId}?sessionId={sessionId}"
    width="100%"
    height="600px"
    frameborder="0"
></iframe>
```


# Topic Mosaic
Source: https://docs.forestreet.com/api-reference/ui-components/topic-mosaic

Transform complex market data into clear, interactive visual insights for rapid understanding and informed decision-making

## Example: 'Digital Labor' Technologies Market

[https://ailsa.forestreet.com/embed/mosaic/3260](https://ailsa.forestreet.com/embed/mosaic/3260)

### Introduction

The Market Topic Mosaic is a visual representation designed to illustrate the various market segments and the
interconnectivity between different topics. This widget provides a user-friendly interface for exploring common topics
that are talked about within a market.

## Benefits

* Enhanced Market Understanding: Offers a clear visual representation of complex market segments, aiding in
  comprehending and identifying key trends and areas.

* Interactive and Engaging: Allows users to interactively explore topics, fostering a deeper understanding and
  engagement compared to static data formats.

* Efficient Decision-Making: Facilitates quick assimilation of information, enabling rapid identification of interests
  or concerns for faster, more informed decision-making.

* Trend and Pattern Recognition: Simplifies the recognition of visual trends and patterns, aiding in spotting emerging
  market changes.

* Customisable and Dynamic: Provides a customisable, real-time view of market data, catering to diverse user needs and
  ensuring up-to-date market insights.

## Using In Your Own Web-pages / Web-apps

The Forestreet Topic Mosaic is simple to use and embed in any webpage or webapp.

Simply copy and paste the HTML snippet below, providing a marketId at the end of the src URL. You can provide any
marketId found within the Forestreet database. Markets can be searched using the Search Market endpoint.

```html theme={null}
<iframe width="100%" height="{600}" src="https://ailsa.forestreet.com/embed/mosaic/{marketId}" />
```