HighLevel: Search Opportunity

← Opportunities operations · Get started

Operation gohighlevel.search_opportunity

Provider route: GET /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"]["searchOpportunity"]>[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.searchOpportunity(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_opportunity(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.q	string	Optional
query.status	string	Optional	One of: open, won, lost, abandoned, all
query.campaignId	string	Optional
query.id	string	Optional
query.order	string	Optional
query.endDate	string	Optional
query.startAfter	string	Optional
query.startAfterId	string	Optional
query.date	string	Optional
query.country	string	Optional
query.page	number	Optional	Default: 1
query.limit	number	Optional	Default: 20
query.getTasks	boolean	Optional
query.getNotes	boolean	Optional
query.getCalendarEvents	boolean	Optional
query.locationId	string	Required within parent
query.pipelineId	string	Optional
query.pipelineStageId	string	Optional
query.contactId	string	Optional
query.assignedTo	string	Optional

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 Opportunity — response body

Referenced models: Search Opportunity — response body

Schemas

Search Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
aggregations	object	Optional	Aggregation results keyed by aggregation name
meta	JSON	Optional	Pagination metadata for the result set
meta (allOf 1)	Model	All variants apply	Expand Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total
opportunities	array	Optional	List of opportunities matching the search criteria
opportunities[]	Model	Each item	Expand Search Opportunity — response body — opportunities item

Referenced models: Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total, Search Opportunity — response body — opportunities item

Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total

Field	Type	Presence	Description and constraints
$	object	Root
currentPage	JSON	Optional
currentPage (anyOf 1)	number	Alternative	Current page number
currentPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
nextPage	JSON	Optional
nextPage (anyOf 1)	number	Alternative	Next page number
nextPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
nextPageUrl	string	Optional	URL to retrieve the next page of results
prevPage	JSON	Optional
prevPage (anyOf 1)	number	Alternative	Previous page number
prevPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startAfter	JSON	Optional
startAfter (anyOf 1)	number	Alternative	Cursor timestamp to use for pagination (startAfter param)
startAfter (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startAfterId	string	Optional	Cursor id to use for pagination (startAfterId param)
total	JSON	Optional
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]+)?$

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 Opportunity — response body — opportunities item custom Fields item

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	JSON	Required within parent	The value of the custom field
fieldValue (anyOf 1)	string	Alternative
fieldValue (anyOf 2)	object	Alternative
fieldValue (anyOf 3)	array	Alternative
fieldValue (anyOf 3)[]	string	Each item
fieldValue (anyOf 4)	array	Alternative
fieldValue (anyOf 4)[]	object	Each item
id	string	Required within parent	Unique identifier of the custom field

Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags

Field	Type	Presence	Description and constraints
$	object	Root
companyName	string	Optional	Company name associated with the contact
email	string	Optional	Email address of the contact
id	string	Optional	Unique identifier of the contact
name	string	Optional	Full name of the contact
phone	string	Optional	Phone number of the contact
tags	array	Optional	Tags associated with the contact
tags[]	string	Each item

Policy, approvals and errors

SDK function policy ID: gohighlevel.search_opportunity. Catalog operation: search-opportunity. 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