> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Opportunities

> Search referral opportunities by connector, company, or across your entire network

Search opportunities with optional filters. All parameters are optional. Call with no filters to list all opportunities, or combine filters to narrow results.

To search for a specific connector's opportunities, use the [`/by-connector`](/api-reference/search-by-connector) variant: `GET /network/search/opportunities/by-connector?linkedin_public_id=john-doe`.

To find who can introduce you to a specific **prospect**, filter this endpoint by `prospect_linkedin_urls` instead: `GET /network/search/opportunities?prospect_linkedin_urls=https://www.linkedin.com/in/jane-smith`. The `/by-connector` variant matches the connector side only and will return `0` results for a prospect.

## People with several current roles

Plenty of people hold more than one job at a time. A partner at a venture fund may also sit on the boards
of three companies the fund backs, and each opportunity is filed under a single one of those companies.
Company filters match **every role a person currently holds**, not just the one their opportunity is filed
under, so a search for the fund finds that partner. This needs no parameter and is always on.

Past employers are not matched. Someone who left a company is not an opportunity at that company.

Add `include_all_positions=true` to see the full picture in the response: every job each person holds or
held, with `is_current` separating the two and `is_primary` marking the role the opportunity is filed under.

## Who to ask for the introduction

Each `client` (the connector) carries `owner_email` and `owner_name`: the team member who owns
that connector, and therefore the person to ask. Both are omitted when the connector has no
owner, so absence means unowned rather than unknown.

They are returned here so you do not have to resolve them yourself. Paging
[`/network/connectors`](/api-reference/list-connectors) to build an owner map costs one request
per 100 connectors, which becomes the slowest part of a sidepanel once a network passes a few
hundred connectors.

## Query Parameters

### Company filters

<ParamField query="domains" type="string">
  Comma-separated company domains (e.g. `acme.com,stripe.com`)
</ParamField>

<ParamField query="linkedin_urls" type="string">
  Comma-separated company LinkedIn URLs
</ParamField>

<ParamField query="numeric_ids" type="string">
  Comma-separated LinkedIn numeric IDs
</ParamField>

<ParamField query="vanity_names" type="string">
  Comma-separated LinkedIn vanity names
</ParamField>

### Client/prospect filters

<ParamField query="client_names" type="string">
  Comma-separated client (connector) names
</ParamField>

<ParamField query="client_linkedin_urls" type="string">
  Comma-separated client LinkedIn URLs
</ParamField>

<ParamField query="client_public_identifiers" type="string">
  Comma-separated client LinkedIn public identifiers
</ParamField>

<ParamField query="client_companies" type="string">
  Comma-separated client company names
</ParamField>

<ParamField query="prospect_names" type="string">
  Comma-separated prospect names
</ParamField>

<ParamField query="prospect_linkedin_urls" type="string">
  Comma-separated prospect LinkedIn URLs
</ParamField>

<ParamField query="prospect_positions" type="string">
  Comma-separated prospect job titles
</ParamField>

<ParamField query="prospect_companies" type="string">
  Comma-separated prospect company names
</ParamField>

<ParamField query="owners" type="string">
  Comma-separated owners, each either an owner UUID from [List Owners](/api-reference/list-owners) or an owner email address. Addresses are matched case-insensitively; one that belongs to no owner simply matches nothing.
</ParamField>

### Scoring and engagement filters

<ParamField query="seniority_levels" type="string">
  `high`, `mid`, `low`
</ParamField>

<ParamField query="industries" type="string">
  Comma-separated industry names
</ParamField>

<ParamField query="countries" type="string">
  Comma-separated country names
</ParamField>

<ParamField query="confidence_ranges" type="string">
  e.g. `80-100,60-79`
</ParamField>

<ParamField query="employee_ranges" type="string">
  Comma-separated employee count ranges (e.g. `51-200,501-1000`)
</ParamField>

<ParamField query="revenue_ranges" type="string">
  Comma-separated revenue ranges
</ParamField>

<ParamField query="statuses" type="string">
  Comma-separated opportunity statuses
</ParamField>

<ParamField query="engagement_types" type="string">
  Comma-separated engagement types
</ParamField>

<ParamField query="crm_statuses" type="string">
  Comma-separated CRM statuses
</ParamField>

### Date and behavior filters

<ParamField query="created_after" type="string">
  Filter by creation date (YYYY-MM-DD)
</ParamField>

<ParamField query="created_before" type="string">
  Filter by creation date (YYYY-MM-DD)
</ParamField>

<ParamField query="exclude_client_companies" type="boolean" default="false">
  Exclude prospects at the same company as the client
</ParamField>

<ParamField query="include_unengaged" type="boolean" default="false">
  Include opportunities with no engagement
</ParamField>

<ParamField query="full_history" type="boolean" default="false">
  Include full engagement history
</ParamField>

<ParamField query="force_refresh" type="boolean" default="false">
  Bypass cache and fetch fresh results
</ParamField>

<ParamField query="include_all_positions" type="boolean" default="false">
  Return every job each person holds or held, as a `positions` array on the person, alongside the single
  role the opportunity is filed under. Requires a bounded `page_size`: combining this with the unlimited
  page returns 400, so page through the results instead.
</ParamField>

<ParamField query="job_id" type="string">
  Filter by import job ID
</ParamField>

### Pagination

<ParamField query="page" type="integer" default="1" />

<ParamField query="page_size" type="integer" default="25" />

<ParamField query="sort_field" type="string" />

<ParamField query="sort_direction" type="string" />

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.clustr-ai.com/api/public/network/search/opportunities?domains=acme.com&confidence_ranges=80-100&page_size=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "results": [
        {
          "client": {
            "name": "John Doe",
            "job_title": "Sales Director",
            "owner_email": "alice@company.com",
            "owner_name": "Alice Martin"
          },
          "opportunities": [
            {
              "opportunity_id": "opp_abc123",
              "prospect": {
                "name": "Jane Smith",
                "job_title": "CTO",
                "company_name": "Acme Corp",
                "positions": [
                  {
                    "company_name": "Acme Corp",
                    "linkedin_numeric_id": "12345678",
                    "linkedin_vanity_name": "acme-corp",
                    "domain": "acme.com",
                    "job_title": "CTO",
                    "is_current": true,
                    "is_primary": true
                  },
                  {
                    "company_name": "Northwind Ventures",
                    "linkedin_numeric_id": "74364633",
                    "linkedin_vanity_name": "northwind-ventures",
                    "job_title": "Board member",
                    "is_current": true,
                    "is_primary": false
                  }
                ]
              },
              "relationship": { "confidence_score": 92, "total_overlap_months": 36 },
              "is_target_company": true
            }
          ]
        }
      ],
      "total": 42,
      "page": 1,
      "page_size": 25,
      "has_more": true
    }
  }
  ```
</ResponseExample>