Opportunity Search Setup

Query your GoHighLevel opportunities with filters for pipeline, stage, status, value, and date range. This guide walks you through the search endpoint with full pagination support.

Prerequisites

Before you begin, confirm the following:

• A GoHighLevel sub-account with existing opportunities in at least one pipeline
• A Private Integration Token (PIT) with the opportunities scope enabled
• Your locationId (sub-account ID) from Settings > Business Info
• At least one pipeline with multiple stages to test filtering
• A REST client like Postman, Insomnia, or curl ready to use

Set Up Authentication

The search endpoint uses the same Bearer token authentication as all opportunity endpoints.

1. Go to Settings > Integrations > Private Integrations
2. Use an existing PIT with opportunities scope, or create a new one
3. Copy the token and set it as an environment variable:

export GHL_TOKEN="your-private-integration-token"
export LOCATION_ID="your-location-id"

Required headers for every request:

Authorization: Bearer $GHL_TOKEN
Content-Type: application/json
Version: 2021-07-28

Make Your First Call

The search endpoint is GET /opportunities/search with query parameters for filtering.

Basic search returning all opportunities in a location:

curl -X GET "https://services.leadconnectorhq.com/opportunities/search?location_id=$LOCATION_ID" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Filter by pipeline and status:

curl -X GET "https://services.leadconnectorhq.com/opportunities/search?\
location_id=$LOCATION_ID&\
pipeline_id=your-pipeline-id&\
status=open" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Filter by stage and date range:

curl -X GET "https://services.leadconnectorhq.com/opportunities/search?\
location_id=$LOCATION_ID&\
pipeline_stage_id=your-stage-id&\
date=2026-01-01&\
endDate=2026-03-07" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Paginate results using limit and startAfterId:

curl -X GET "https://services.leadconnectorhq.com/opportunities/search?\
location_id=$LOCATION_ID&\
limit=20&\
startAfterId=last-opportunity-id" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Available filter parameters include pipeline_id, pipeline_stage_id, status (open, won, lost, abandoned), monetaryValue, assignedTo, contactId, date, endDate, q (text search on name), limit, and startAfterId.

Handle the Response

A successful 200 response returns a JSON object with two key fields:

• opportunities — An array of opportunity objects, each containing id, name, monetaryValue, status, pipelineId, pipelineStageId, contact, and assignedTo
• meta — Pagination metadata including total, currentPage, nextPageUrl, and startAfterId

Use meta.startAfterId as the startAfterId query param in your next request to paginate through large result sets. When meta.startAfterId is null, you have reached the last page.

Common errors:

• 400 — Invalid filter parameter. Check that date formats use YYYY-MM-DD.
• 401 — Token missing or invalid. Verify your PIT.
• 422 — Missing location_id. This parameter is always required.

Test Your Setup

Walk through these steps to validate your search configuration:

1. Run a basic search with only location_id and confirm you get results
2. Add a pipeline_id filter and verify the results belong to that pipeline only
3. Filter by status=won and confirm all returned opportunities have won status
4. Set limit=2 and use startAfterId from the first response to page through results
5. Compare the API results against what you see in the GHL Opportunities dashboard

If result counts differ, check that your PIT has access to all pipelines. Some integrations only see pipelines they were granted access to.

Next Steps

Read the full Opportunity Search guide for advanced query patterns and aggregation tips. Use Opportunity CRUD to act on search results, or set up the Pipeline Getter to dynamically retrieve pipeline and stage IDs for your filters.