# Search Opportunities — Lever

> Searches and filters opportunities (candidate applications) in Lever. This is the primary tool for finding candidates — use it whenever asked to find, list, or filter candidates or applications. Supports filtering by job posting, pipeline…

- Key: `lever-search-opportunities`
- Type: Action (Read-only)
- Version: 0.0.2
- App: Lever (`lever`) — https://pipedream.com/apps/lever.md
- This page (HTML): https://pipedream.com/apps/lever/actions/search-opportunities
- Hints: read-only · open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/lever/actions/search-opportunities/search-opportunities.mjs

## Description

Searches and filters opportunities (candidate applications) in Lever. This is the primary tool for finding candidates — use it whenever asked to find, list, or filter candidates or applications. Supports filtering by job posting, pipeline stage, tag, origin, email, and archived status. Use **List Postings** to find posting IDs, **List Stages** to find stage IDs. The Lever API has no name or owner filter. To find a candidate **by name**, pass the name in `email`: when the value isn't a valid email address this tool lists opportunities and matches them by name/email locally (it does not send an invalid `email` to the API). The local name match sweeps up to the first several pages of results; if that cap is reached the `$summary` says so and the response `next` cursor lets you continue. When the user says 'my candidates', note that the API does not support filtering by owner directly — search by posting or stage and identify relevant records from the results. Set expand to include related objects inline (e.g. `stage`, `owner`, `contact`) and avoid follow-up calls. Returns cursor-paginated results; use the `next` field in the response to fetch subsequent pages. Example: to find a candidate by email, call with email="jane@example.com" → exact match; to find by name, call with email="Jane Doe" → local name match. [See the documentation](https://hire.lever.co/developer/documentation#list-all-opportunities)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `postingId` | `string` | No | Filter by job posting. Use List Postings to find posting IDs. |
| `stageId` | `string` | No | Filter by pipeline stage. Use List Stages to find stage IDs. |
| `tag` | `string` | No | Filter by a single tag applied to the opportunity. |
| `origin` | `string` | No | Filter by how the candidate entered the pipeline. |
| `email` | `string` | No | Find a candidate. Pass a full email address for an exact server-side match. The Lever API has no name search, so if you pass a name or partial here instead, this tool lists opportunities and matches them by name/email locally rather than sending an invalid address to the API. |
| `archived` | `boolean` | No | Set to true to return only archived opportunities, false for active only. Omit to return all. |
| `expand` | `string[]` | No | Inline related objects in the response to avoid follow-up calls. Options: applications, stage, owner, followers, sourcedBy, contact. |
| `limit` | `integer` | No | Maximum number of opportunities to return (1–100). Defaults to 100. |
| `offset` | `string` | No | Pagination cursor. Pass the next value from a previous response to fetch the next page. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "lever",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "lever-search-opportunities",
  arguments: {
    postingId: "Posting ID",
    stageId: "Stage ID",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "lever-search-opportunities",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    lever: { authProvisionId: "apn_xxxxxxx" },
    postingId: "Posting ID",
    stageId: "Stage ID",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "lever-search-opportunities",
    "configured_props": {
      "lever": { "authProvisionId": "apn_xxxxxxx" },
      "postingId": "Posting ID",
      "stageId": "Stage ID"
    }
  }'
```

---

- App: https://pipedream.com/apps/lever.md · All apps: https://pipedream.com/apps