Lever ACTION
Search Opportunities
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- Action
- Read only
- OAuth
- SDK
- MCP
IMPLEMENTATION
Call this tool
Connect a user's Lever account once, then configure and run Search Opportunities from your backend or agent.
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 -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"
}
}'// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{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",
},
})SCHEMA
Inputs
Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.
| Property | Type | Description |
|---|---|---|
postingId Posting ID | string | Filter by job posting. Use List Postings to find posting IDs. Optional |
stageId Stage ID | string | Filter by pipeline stage. Use List Stages to find stage IDs. Optional |
tag Tag | string | Filter by a single tag applied to the opportunity. Optional |
origin Origin | string | Filter by how the candidate entered the pipeline. Optional |
email Email or name | string | 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. Optional |
archived Archived | boolean | Set to true to return only archived opportunities, false for active only. Omit to return all. Optional |
expand Expand | string[] | Inline related objects in the response to avoid follow-up calls. Options: applications, stage, owner, followers, sourcedBy, contact. Optional |
limit Limit | integer | Maximum number of opportunities to return (1–100). Defaults to 100. Optional |
offset Offset (cursor) | string | Pagination cursor. Pass the next value from a previous response to fetch the next page. Optional |
REFERENCE
Tool details
Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.
- Registry key
- lever-search-opportunities
- Version
- 0.0.2
- App
- Lever
- Authentication
- OAuth
- Read-only
- Yes
- Destructive
- No
- Open world
- Yes
- Source
- View on GitHub ↗