# Search Opportunity GET https://services.leadconnectorhq.com/opportunities/search Search Opportunity ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `opportunities.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `q` | string | No | Search query (max 75 characters) | | `status` | string | No | Filter by opportunity status | | `campaignId` | string | No | Campaign Id | | `id` | string | No | Opportunity Id | | `order` | string | No | Sort order for results (e.g. added_asc, added_desc, name_asc, name_desc) | | `endDate` | string | No | End date | | `startAfter` | string | No | Cursor timestamp (epoch ms) for pagination. | | `startAfterId` | string | No | Start After Id | | `date` | string | No | Start date | | `country` | string | No | Filter by country code (ISO 3166-1 alpha-2) | | `page` | number | No | Page number for pagination | | `limit` | number | No | Limit Per Page records count. will allow maximum up to 100 and default will be 20 | | `getTasks` | boolean | No | get Tasks in contact | | `getNotes` | boolean | No | get Notes in contact | | `getCalendarEvents` | boolean | No | get Calender event in contact | | `locationId` | string | Yes | Location Id | | `pipelineId` | string | No | Pipeline Id | | `pipelineStageId` | string | No | Stage Id | | `contactId` | string | No | Contact Id | | `assignedTo` | string | No | Filter by assigned user identifier | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "HighLevel API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/opportunities/search": { "get": { "summary": "Search Opportunity", "operationId": "searchOpportunity", "description": "Search Opportunity", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } }, { "name": "q", "required": false, "in": "query", "description": "Search query (max 75 characters)", "schema": { "example": "john@deo.com", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by opportunity status", "schema": { "example": "open", "enum": [ "open", "won", "lost", "abandoned", "all" ], "type": "string" } }, { "name": "campaignId", "required": false, "in": "query", "description": "Campaign Id", "schema": { "example": "Y2I9XM7aO1hncuSOlc9L", "type": "string" } }, { "name": "id", "required": false, "in": "query", "description": "Opportunity Id", "schema": { "example": "123akv4LFn6C9frZoy3e", "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Sort order for results (e.g. added_asc, added_desc, name_asc, name_desc)", "schema": { "example": "added_asc", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date", "schema": { "example": "mm-dd-yyyy", "type": "string" } }, { "name": "startAfter", "required": false, "in": "query", "description": "Cursor timestamp (epoch ms) for pagination.", "schema": { "example": "1628008053263", "type": "string" } }, { "name": "startAfterId", "required": false, "in": "query", "description": "Start After Id", "schema": { "example": "UIaE1WjAwWKdlyD7osQI", "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Start date", "schema": { "example": "mm-dd-yyyy", "type": "string" } }, { "name": "country", "required": false, "in": "query", "description": "Filter by country code (ISO 3166-1 alpha-2)", "schema": { "example": "US", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Limit Per Page records count. will allow maximum up to 100 and default will be 20", "schema": { "default": 20, "example": 20, "type": "number" } }, { "name": "getTasks", "required": false, "in": "query", "description": "get Tasks in contact", "schema": { "example": false, "type": "boolean" } }, { "name": "getNotes", "required": false, "in": "query", "description": "get Notes in contact", "schema": { "example": false, "type": "boolean" } }, { "name": "getCalendarEvents", "required": false, "in": "query", "description": "get Calender event in contact", "schema": { "example": false, "type": "boolean" } }, { "name": "locationId", "required": true, "in": "query", "description": "Location Id", "schema": { "example": "i2SpAtBVHSVea1sL6oah", "type": "string" } }, { "name": "pipelineId", "required": false, "in": "query", "description": "Pipeline Id", "schema": { "example": "bCkKGpDsyPP4peuKowkG", "type": "string" } }, { "name": "pipelineStageId", "required": false, "in": "query", "description": "Stage Id", "schema": { "example": "7915dedc-8f18-44d5-8bc3-77c04e994a10", "type": "string" } }, { "name": "contactId", "required": false, "in": "query", "description": "Contact Id", "schema": { "example": "WFwVrSSjZ2CNHbZThQX2", "type": "string" } }, { "name": "assignedTo", "required": false, "in": "query", "description": "Filter by assigned user identifier", "schema": { "example": "082goXVW3lIExEQPOnd3", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSuccessfulResponseDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } } }, "security": [ { "bearer": [ "opportunities.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "SearchSuccessfulResponseDto": { "type": "object", "properties": { "opportunities": { "description": "List of opportunities matching the search criteria", "example": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the opportunity", "example": "yWQobCRIhRguQtD2llvk" }, "name": { "type": "string", "description": "Name of the opportunity", "example": "testing" }, "monetaryValue": { "type": "number", "description": "Monetary value of the opportunity", "example": 500 }, "pipelineId": { "type": "string", "description": "Identifier of the pipeline the opportunity belongs to", "example": "VDm7RPYC2GLUvdpKmBfC" }, "pipelineStageId": { "type": "string", "description": "Identifier of the pipeline stage the opportunity is in", "example": "e93ba61a-53b3-45e7-985a-c7732dbcdb69" }, "assignedTo": { "type": "string", "description": "Identifier of the user the opportunity is assigned to", "example": "zT46WSCPbudrq4zhWMk6" }, "status": { "type": "string", "description": "Current status of the opportunity", "example": "open" }, "source": { "type": "string", "description": "Source of the opportunity", "example": "" }, "lastStatusChangeAt": { "type": "string", "description": "ISO 8601 timestamp of the last status change", "example": "2021-08-03T04:55:17.355Z" }, "lastStageChangeAt": { "type": "string", "description": "ISO 8601 timestamp of the last stage change", "example": "2021-08-03T04:55:17.355Z" }, "lastActionDate": { "type": "string", "description": "ISO 8601 timestamp of the last action on the opportunity", "example": "2021-08-03T04:55:17.355Z" }, "indexVersion": { "type": "string", "description": "Index version of the opportunity record", "example": 1 }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the opportunity was created", "example": "2021-08-03T04:55:17.355Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the opportunity was last updated", "example": "2021-08-03T04:55:17.355Z" }, "forecastExpectedCloseDate": { "type": "string", "description": "Expected close date for the forecast (YYYY-MM-DD)", "example": "2026-05-20" }, "forecastOriginalCloseDate": { "type": "string", "description": "Original forecast close date before any slippage (YYYY-MM-DD)", "example": "2026-05-01" }, "forecastSlippageCount": { "type": "number", "description": "Number of times the close date has slipped", "example": 2 }, "forecastDaysSlipped": { "type": "number", "description": "Total days the close date has slipped", "example": 19 }, "forecastLastSlippedAt": { "type": "string", "description": "ISO 8601 timestamp of the last close-date slip", "example": "2026-05-22T10:30:00.000Z" }, "forecastProbability": { "type": "number", "description": "Forecast win probability percentage (0–100)", "example": 20 }, "effectiveProbability": { "type": "number", "description": "Effective win probability after stage and forecast adjustments (0–100)", "example": 40 }, "contactId": { "type": "string", "description": "Identifier of the contact linked to the opportunity", "example": "zT46WSCPbudrq4zhWMk6" }, "locationId": { "type": "string", "description": "Identifier of the location (sub-account) the opportunity belongs to", "example": "zT46WSCPbudrq4zhW" }, "contact": { "description": "Contact details associated with the opportunity", "example": {}, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the contact", "example": "byMEV0NQinDhq8ZfiOi2" }, "name": { "type": "string", "description": "Full name of the contact", "example": "John Deo" }, "companyName": { "type": "string", "description": "Company name associated with the contact", "example": "Tesla Inc" }, "email": { "type": "string", "description": "Email address of the contact", "example": "john@deo.com" }, "phone": { "type": "string", "description": "Phone number of the contact", "example": "+1202-555-0107" }, "tags": { "description": "Tags associated with the contact", "example": [ "lead", "vip" ], "type": "array", "items": { "type": "string" } } }, "title": "SearchOpportunitiesContactResponseSchema" } ] }, "notes": { "description": "Notes attached to the opportunity", "example": [], "type": "array", "items": { "type": "array" } }, "tasks": { "description": "Tasks attached to the opportunity", "example": [], "type": "array", "items": { "type": "array" } }, "calendarEvents": { "description": "Calendar events attached to the opportunity", "example": [], "type": "array", "items": { "type": "array" } }, "lostReasonId": { "type": "string", "description": "Identifier of the lost reason if the opportunity was marked lost", "example": "zT46WSCPbudrq4zhWMk6" }, "customFields": { "description": "Custom fields associated with the opportunity", "example": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the custom field", "example": "MgobCB14YMVKuE4Ka8p1" }, "fieldValue": { "description": "The value of the custom field", "example": "custom field value", "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object" } } ] } }, "required": [ "id", "fieldValue" ], "title": "CustomFieldResponseSchema" } }, "followers": { "description": "User IDs following this opportunity", "example": [ "sx6wyHhbFdRXh302Lunr" ], "type": "array", "items": { "type": "array" } }, "externalObjectId": { "type": "string", "description": "External object identifier for integrations", "example": "ext_obj_12345" } }, "title": "SearchOpportunitiesResponseSchema" } }, "meta": { "description": "Pagination metadata for the result set", "example": {}, "allOf": [ { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of opportunities matching the query", "example": 1 }, "nextPageUrl": { "type": "string", "description": "URL to retrieve the next page of results", "example": "http://localhost:5066/opportunities/search?q=&location_id=ve9EPM428h8vShlRW1KT&pipeline_id=&pipeline_stage_id=&status=&assigned_to+=&campaignId=&id=&order=&endDate=&startAfter=1625203104328&startAfterId=yWQobCRIhRguQtD2llvk&date=&limit=1&country=&page=1" }, "startAfterId": { "type": "string", "description": "Cursor id to use for pagination (startAfterId param)", "example": "yWQobCRIhRguQtD2llvk" }, "startAfter": { "type": "number", "description": "Cursor timestamp to use for pagination (startAfter param)", "example": 1625203104328 }, "currentPage": { "type": "number", "description": "Current page number", "example": 2 }, "nextPage": { "type": "number", "description": "Next page number", "example": 3 }, "prevPage": { "type": "number", "description": "Previous page number", "example": 1 } }, "title": "SearchMetaResponseSchema" } ] }, "aggregations": { "type": "object", "description": "Aggregation results keyed by aggregation name", "example": {} } }, "title": "SearchSuccessfulResponseDto" }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" } } } } ``` ## HighLevel SDK Examples **Node.js** (`@gohighlevel/api-client`) ```javascript import HighLevel from '@gohighlevel/api-client'; const ghl = new HighLevel({ privateIntegrationToken: '' }); const response = await ghl.opportunities.searchOpportunity({ locationId: '' }); console.log(response); ``` **Python** (`gohighlevel-api-client`) ```python from highlevel import HighLevel client = HighLevel( private_integration_token='' ) response = await client.opportunities.search_opportunity(locationId='') print(response) ``` **PHP** (`gohighlevel/api-client`) ```php '' ]); $ghl = new HighLevel($config); $response = $ghl->opportunities->searchOpportunity(['locationId' => '']); echo json_encode($response, JSON_PRETTY_PRINT); ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/opportunities/search?locationId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/opportunities/search?locationId=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/opportunities/search" headers = { "Authorization": "Bearer ", "Version": "v3" } params = { "locationId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/opportunities/search?locationId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/opportunities/search?locationId=") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/opportunities/search?locationId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/opportunities/search?locationId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/opportunities/search?locationId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```