HighLevel: Search Opportunities

← Opportunities operations · Get started

Operation gohighlevel.search_opportunities_advanced

Provider route: POST /opportunities/search. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["opportunities"]["searchOpportunitiesAdvanced"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.opportunities.searchOpportunitiesAdvanced(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.opportunities.search_opportunities_advanced(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Search Opportunities — request body — body

Referenced models: Search Opportunities — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Search Opportunities — response body

Referenced models: Search Opportunities — response body

Schemas

2 more schemas are linked from the tables above, on the schema pages.

Search Opportunities — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
additionalDetails	JSON	Required within parent	Flags to include additional related entities in the response
additionalDetails (allOf 1)	Model	All variants apply	Expand Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations
limit	number	Required within parent	Maximum number of results to return per page
locationId	string	Required within parent	Location Id
page	number	Required within parent	Page number (0-indexed)
query	string	Required within parent	Full-text search query string (max 75 characters)
searchAfter	array	Required within parent	Search-after cursor values for deep pagination
searchAfter[]	string	Each item

Referenced models: Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations

Search Opportunities — response body

Field	Type	Presence	Description and constraints
$	object	Root
aggregations	object	Optional	Aggregation results keyed by aggregation name
opportunities	array	Optional	List of opportunities matching the search criteria
opportunities[]	Model	Each item	Expand Search Opportunity — response body — opportunities item
stageAggregations	array	Optional	Per-stage totals when pipeline filter is present
stageAggregations[]	Model	Each item	Expand Search Opportunities — response body — stage Aggregations item
total	JSON	Required within parent
total (anyOf 1)	number	Alternative	Total number of opportunities matching the query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Search Opportunity — response body — opportunities item, Search Opportunities — response body — stage Aggregations item

Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations

Field	Type	Presence	Description and constraints
$	object	Root
calendarEvents	boolean	Required within parent	Include calendar events in the response
notes	boolean	Required within parent	Include notes in the response
tasks	boolean	Required within parent	Include tasks in the response
unReadConversations	boolean	Required within parent	Include unread conversations count in the response

Search Opportunity — response body — opportunities item

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Identifier of the user the opportunity is assigned to
calendarEvents	array	Optional	Calendar events attached to the opportunity
calendarEvents[]	array	Each item
contact	JSON	Optional	Contact details associated with the opportunity
contact (allOf 1)	Model	All variants apply	Expand Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags
contactId	string	Optional	Identifier of the contact linked to the opportunity
createdAt	string	Optional	ISO 8601 timestamp when the opportunity was created
customFields	array	Optional	Custom fields associated with the opportunity
customFields[]	Model	Each item	Expand Search Opportunity — response body — opportunities item custom Fields item
effectiveProbability	JSON	Optional
effectiveProbability (anyOf 1)	number	Alternative	Effective win probability after stage and forecast adjustments (0–100)
effectiveProbability (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
externalObjectId	string	Optional	External object identifier for integrations
followers	array	Optional	User IDs following this opportunity
followers[]	array	Each item
forecastDaysSlipped	JSON	Optional
forecastDaysSlipped (anyOf 1)	number	Alternative	Total days the close date has slipped
forecastDaysSlipped (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forecastExpectedCloseDate	string	Optional	Expected close date for the forecast (YYYY-MM-DD)
forecastLastSlippedAt	string	Optional	ISO 8601 timestamp of the last close-date slip
forecastOriginalCloseDate	string	Optional	Original forecast close date before any slippage (YYYY-MM-DD)
forecastProbability	JSON	Optional
forecastProbability (anyOf 1)	number	Alternative	Forecast win probability percentage (0–100)
forecastProbability (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forecastSlippageCount	JSON	Optional
forecastSlippageCount (anyOf 1)	number	Alternative	Number of times the close date has slipped
forecastSlippageCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
id	string	Optional	Unique identifier of the opportunity
indexVersion	string	Optional	Index version of the opportunity record
lastActionDate	string	Optional	ISO 8601 timestamp of the last action on the opportunity
lastStageChangeAt	string	Optional	ISO 8601 timestamp of the last stage change
lastStatusChangeAt	string	Optional	ISO 8601 timestamp of the last status change
locationId	string	Optional	Identifier of the location (sub-account) the opportunity belongs to
lostReasonId	string	Optional	Identifier of the lost reason if the opportunity was marked lost
monetaryValue	JSON	Optional
monetaryValue (anyOf 1)	number	Alternative	Monetary value of the opportunity
monetaryValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Optional	Name of the opportunity
notes	array	Optional	Notes attached to the opportunity
notes[]	array	Each item
pipelineId	string	Optional	Identifier of the pipeline the opportunity belongs to
pipelineStageId	string	Optional	Identifier of the pipeline stage the opportunity is in
source	string	Optional	Source of the opportunity
status	string	Optional	Current status of the opportunity
tasks	array	Optional	Tasks attached to the opportunity
tasks[]	array	Each item
updatedAt	string	Optional	ISO 8601 timestamp when the opportunity was last updated

Referenced models: Search Opportunity — response body — opportunities item custom Fields item, Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags

Search Opportunities — response body — stage Aggregations item

Field	Type	Presence	Description and constraints
$	object	Root
openValue	JSON	Required within parent
openValue (anyOf 1)	number	Alternative	Total value of open opportunities in this stage
openValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
openWeightedValue	JSON	Required within parent
openWeightedValue (anyOf 1)	number	Alternative	Probability-weighted value of open opportunities in this stage
openWeightedValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pipelineStageId	string	Required within parent	Identifier of the pipeline stage being aggregated
totalCount	JSON	Required within parent
totalCount (anyOf 1)	number	Alternative	Total number of opportunities in this stage
totalCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
totalValue	JSON	Required within parent
totalValue (anyOf 1)	number	Alternative	Total monetary value of all opportunities in this stage
totalValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
weightedValue	JSON	Required within parent
weightedValue (anyOf 1)	number	Alternative	Probability-weighted total value of opportunities in this stage
weightedValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
wonValue	JSON	Required within parent
wonValue (anyOf 1)	number	Alternative	Total value of won opportunities in this stage
wonValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Policy, approvals and errors

SDK function policy ID: gohighlevel.search_opportunities_advanced. Catalog operation: search-opportunities-advanced. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["opportunities.readonly"]

Pinned headers: {"Version": "v3"}

Official provider source