# Search Opportunities

POST https://services.leadconnectorhq.com/opportunities/search

Search Opportunities based on combinations of advanced filters. Documentation Link - https://doc.clickup.com/8631005/d/h/87cpx-424216/7bf11bc9b94f80f

## Authentication

Send `Authorization: Bearer <token>` 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 |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "HighLevel API",
    "version": "v3"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/opportunities/search": {
      "post": {
        "summary": "Search Opportunities",
        "operationId": "searchOpportunities",
        "description": "Search Opportunities based on combinations of advanced filters. Documentation Link - https://doc.clickup.com/8631005/d/h/87cpx-424216/7bf11bc9b94f80f",
        "parameters": [
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v3"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OpportunitySearchBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostSearchSuccessfulResponseDto"
                }
              }
            }
          },
          "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": {
      "OpportunitySearchBodyDTO": {
        "type": "object",
        "properties": {
          "locationId": {
            "type": "string",
            "description": "Location Id",
            "example": "i2SpAtBVHSVea1sL6oah"
          },
          "query": {
            "type": "string",
            "description": "Full-text search query string (max 75 characters)",
            "example": "john@deo.com"
          },
          "limit": {
            "type": "number",
            "description": "Maximum number of results to return per page",
            "example": 20
          },
          "page": {
            "type": "number",
            "description": "Page number (0-indexed)",
            "example": 0
          },
          "searchAfter": {
            "description": "Search-after cursor values for deep pagination",
            "example": [
              1625203104328,
              "yWQobCRIhRguQtD2llvk"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "additionalDetails": {
            "description": "Flags to include additional related entities in the response",
            "example": {
              "notes": false,
              "tasks": false,
              "calendarEvents": false
            },
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "notes": {
                    "type": "boolean",
                    "description": "Include notes in the response",
                    "example": false
                  },
                  "tasks": {
                    "type": "boolean",
                    "description": "Include tasks in the response",
                    "example": false
                  },
                  "calendarEvents": {
                    "type": "boolean",
                    "description": "Include calendar events in the response",
                    "example": false
                  },
                  "unReadConversations": {
                    "type": "boolean",
                    "description": "Include unread conversations count in the response",
                    "example": false
                  }
                },
                "required": [
                  "notes",
                  "tasks",
                  "calendarEvents",
                  "unReadConversations"
                ],
                "title": "AdditionalDetailsDTO"
              }
            ]
          }
        },
        "required": [
          "locationId",
          "query",
          "limit",
          "page",
          "searchAfter",
          "additionalDetails"
        ],
        "title": "OpportunitySearchBodyDTO"
      },
      "PostSearchSuccessfulResponseDto": {
        "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"
            }
          },
          "total": {
            "type": "number",
            "description": "Total number of opportunities matching the query",
            "example": 100
          },
          "stageAggregations": {
            "description": "Per-stage totals when pipeline filter is present",
            "example": [],
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pipelineStageId": {
                  "type": "string",
                  "description": "Identifier of the pipeline stage being aggregated",
                  "example": "e93ba61a-53b3-45e7-985a-c7732dbcdb69"
                },
                "totalCount": {
                  "type": "number",
                  "description": "Total number of opportunities in this stage",
                  "example": 12
                },
                "totalValue": {
                  "type": "number",
                  "description": "Total monetary value of all opportunities in this stage",
                  "example": 24500
                },
                "weightedValue": {
                  "type": "number",
                  "description": "Probability-weighted total value of opportunities in this stage",
                  "example": 14700
                },
                "openValue": {
                  "type": "number",
                  "description": "Total value of open opportunities in this stage",
                  "example": 18000
                },
                "openWeightedValue": {
                  "type": "number",
                  "description": "Probability-weighted value of open opportunities in this stage",
                  "example": 10800
                },
                "wonValue": {
                  "type": "number",
                  "description": "Total value of won opportunities in this stage",
                  "example": 6500
                }
              },
              "required": [
                "pipelineStageId",
                "totalCount",
                "totalValue",
                "weightedValue",
                "openValue",
                "openWeightedValue",
                "wonValue"
              ],
              "title": "StageAggregationResponseDto"
            }
          },
          "aggregations": {
            "type": "object",
            "description": "Aggregation results keyed by aggregation name",
            "example": {}
          }
        },
        "required": [
          "total"
        ],
        "title": "PostSearchSuccessfulResponseDto"
      },
      "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: '<PRIVATE_INTEGRATION_TOKEN>'
});

const body = {
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
};

const response = await ghl.opportunities.searchOpportunities(body);
console.log(response);
```

**Python** (`gohighlevel-api-client`)

```python
from highlevel import HighLevel

client = HighLevel(
    private_integration_token='<PRIVATE_INTEGRATION_TOKEN>'
)

body = {
    "locationId": "i2SpAtBVHSVea1sL6oah",
    "query": "john@deo.com",
    "limit": 20,
    "page": 0,
    "searchAfter": [
        1625203104328,
        "yWQobCRIhRguQtD2llvk"
    ],
    "additionalDetails": {
        "notes": false,
        "tasks": false,
        "calendarEvents": false
    }
}

response = await client.opportunities.search_opportunities(body=body)
print(response)
```

**PHP** (`gohighlevel/api-client`)

```php
<?php
require_once 'vendor/autoload.php';

use HighLevel\HighLevel;
use HighLevel\HighLevelConfig;

$config = new HighLevelConfig([
    'privateIntegrationToken' => '<PRIVATE_INTEGRATION_TOKEN>'
]);
$ghl = new HighLevel($config);

$body = [
    'locationId' => 'i2SpAtBVHSVea1sL6oah',
    'query' => 'john@deo.com',
    'limit' => 20,
    'page' => 0,
    'searchAfter' => [
        1625203104328,
        'yWQobCRIhRguQtD2llvk'
    ],
    'additionalDetails' => [
        'notes' => false,
        'tasks' => false,
        'calendarEvents' => false
    ]
];

$response = $ghl->opportunities->searchOpportunities($body);
echo json_encode($response, JSON_PRETTY_PRINT);
```

## Code Examples

**cURL**

```bash
curl -L -X POST 'https://services.leadconnectorhq.com/opportunities/search' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: v3' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
}'
```

**Node.js**

```javascript
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: 'v3',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "locationId": "i2SpAtBVHSVea1sL6oah",
      "query": "john@deo.com",
      "limit": 20,
      "page": 0,
      "searchAfter": [
        1625203104328,
        "yWQobCRIhRguQtD2llvk"
      ],
      "additionalDetails": {
        "notes": false,
        "tasks": false,
        "calendarEvents": false
      }
  })
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/opportunities/search', 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 <TOKEN>",
    "Version": "v3"
}

payload = {
    "locationId": "i2SpAtBVHSVea1sL6oah",
    "query": "john@deo.com",
    "limit": 20,
    "page": 0,
    "searchAfter": [
        1625203104328,
        "yWQobCRIhRguQtD2llvk"
    ],
    "additionalDetails": {
        "notes": false,
        "tasks": false,
        "calendarEvents": false
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/opportunities/search',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: v3',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
}',
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .post("https://services.leadconnectorhq.com/opportunities/search")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "v3")
  .header("Content-Type", "application/json")
  .body("{\"locationId\":\"i2SpAtBVHSVea1sL6oah\",\"query\":\"john@deo.com\",\"limit\":20,\"page\":0,\"searchAfter\":[1625203104328,\"yWQobCRIhRguQtD2llvk\"],\"additionalDetails\":{\"notes\":false,\"tasks\":false,\"calendarEvents\":false}}")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
  "strings"
)

func main() {
  url := "https://services.leadconnectorhq.com/opportunities/search"
  payload := strings.NewReader(`{
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
}`)
  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  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")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "v3"
request["Content-Type"] = "application/json"
request.body = '{
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
}'

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "v3"
}

$body = '{
  "locationId": "i2SpAtBVHSVea1sL6oah",
  "query": "john@deo.com",
  "limit": 20,
  "page": 0,
  "searchAfter": [
    1625203104328,
    "yWQobCRIhRguQtD2llvk"
  ],
  "additionalDetails": {
    "notes": false,
    "tasks": false,
    "calendarEvents": false
  }
}'

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/opportunities/search' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json'
$response | ConvertTo-Json
```