Skip to main content

Search Opportunities Advanced

Immutable Catalog Entry

This descriptor comes from the active versioned Portal catalog.

READghl.search_opportunities_advanced
  • Contract tier: agent_ready
  • Risk: read
  • Catalog version: 2026-07-12.2
  • Descriptor hash: 37b796ed04a121ff8b0d59ae5e361412fc04fe3688037fdfb85fe9a6c543ab91

Search GHL opportunities using the official POST /opportunities/search advanced filter endpoint. Use this read-only tool for combinations of filters without changing opportunity data. If query is provided, the MCP applies it as a local text filter because GHL rejects q on the POST endpoint. GHL category: Opportunities. This is a read-only GHL API operation.

Request Body​

{
  "jsonrpc": "2.0",
  "id": "ghl-search-opportunities-advanced-example",
  "method": "tools/call",
  "params": {
    "name": "ghl.search_opportunities_advanced",
    "arguments": {
      "page": 1,
      "limit": 1,
      "query": "query_example",
      "status": "open",
      "country": "country_example",
      "endDate": "endDate_example",
      "tenantId": "tenantId_123",
      "contactId": "contactId_123",
      "startDate": "startDate_example",
      "assignedTo": "assignedTo_example"
    }
  }
}

Arguments Schema​

{
  "type": "object",
  "properties": {
    "page": {
      "type": "number",
      "description": "Page number for paginated results."
    },
    "limit": {
      "type": "number",
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of opportunities to return."
    },
    "query": {
      "type": "string",
      "description": "Local text filter applied to returned opportunity fields. GHL rejects q on this POST endpoint; use search_opportunities for provider-side q search."
    },
    "status": {
      "enum": [
        "open",
        "won",
        "lost",
        "abandoned",
        "all"
      ],
      "type": "string",
      "description": "Filter by opportunity status."
    },
    "country": {
      "type": "string",
      "description": "Filter by country when supported by GHL."
    },
    "endDate": {
      "type": "string",
      "description": "End date filter in the format supported by GHL, commonly mm-dd-yyyy."
    },
    "tenantId": {
      "type": "string",
      "description": "Tenant ID from list_tenants."
    },
    "contactId": {
      "type": "string",
      "description": "Filter by associated GHL contact ID."
    },
    "startDate": {
      "type": "string",
      "description": "Start date filter in the format supported by GHL, commonly mm-dd-yyyy."
    },
    "assignedTo": {
      "type": "string",
      "description": "Filter by assigned GHL user ID."
    },
    "campaignId": {
      "type": "string",
      "description": "Filter by campaign ID when supported by GHL."
    },
    "locationId": {
      "type": "string",
      "description": "Optional GHL location ID. If provided, it must match the authenticated runtime location; otherwise the runtime location is used automatically."
    },
    "pipelineId": {
      "type": "string",
      "description": "Filter by GHL pipeline ID."
    },
    "includeNotes": {
      "type": "boolean",
      "description": "When true, ask GHL to include opportunity notes where supported."
    },
    "includeTasks": {
      "type": "boolean",
      "description": "When true, ask GHL to include opportunity tasks where supported."
    },
    "strictTenant": {
      "type": "boolean",
      "default": true,
      "description": "Require tenantId to match locationId routing (default: true)."
    },
    "pipelineStageId": {
      "type": "string",
      "description": "Filter by GHL pipeline stage ID."
    },
    "includeCalendarEvents": {
      "type": "boolean",
      "description": "When true, ask GHL to include calendar events where supported."
    }
  },
  "additionalProperties": false
}

Output Schema​

{
  "type": "object",
  "required": [
    "ok",
    "data",
    "error",
    "meta"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Whether the GHL MCP operation completed successfully."
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Tool-specific GHL or local navigation result when ok is true."
    },
    "meta": {
      "type": "object",
      "description": "Safe execution, routing, and timing metadata.",
      "additionalProperties": true
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "description": "Safe error details when ok is false; credential values are never returned."
    }
  },
  "description": "Normalized GHL MCP response envelope.",
  "additionalProperties": false
}

Code Examples​

curl -X POST 'https://portal.madpanda3d.com/api/mcp' \
  -H 'Authorization: Bearer mad_live_***' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "ghl-search-opportunities-advanced-example",
  "method": "tools/call",
  "params": {
    "name": "ghl.search_opportunities_advanced",
    "arguments": {
      "page": 1,
      "limit": 1,
      "query": "query_example",
      "status": "open",
      "country": "country_example",
      "endDate": "endDate_example",
      "tenantId": "tenantId_123",
      "contactId": "contactId_123",
      "startDate": "startDate_example",
      "assignedTo": "assignedTo_example"
    }
  }
}'

Example Responses​

{
  "ok": true,
  "message": "Tool ghl.search_opportunities_advanced executed successfully.",
  "note": "Response shape varies by MCP tool. Inspect live responses for exact fields."
}