Skip to main content
POST
Create a new lead search
search_url must be a LinkedIn Sales Navigator search URL (https://www.linkedin.com/sales/search/...). Any other URL, such as a regular LinkedIn search or a profile URL, is rejected with 422 Unprocessable Entity:

Rate Limits

  • 1 request per second per user, on top of your plan’s per-minute limit (see Rate Limiting).
  • With a workspace key, only the workspace’s per-minute limit applies.

With a Workspace Key

With a workspace key, the search joins your workspace’s queue and starts on the first member whose LinkedIn session is free and whose quota covers it. Pass position: "start" to put it ahead of the searches already waiting. expected_profiles_count then comes from the Pipecorn people database, and saved, recent or shared Sales Navigator searches answer 422. See Lead search queue.

Scale Parameter

The scale parameter (boolean, optional) allows you to increase your volume of requests by omitting the following fields:
  • connections_count
  • headline
  • Vanity LinkedIn profile URL (like https://www.linkedin.com/in/mathieu-brun-picard/)
When scale is set to true, you will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL format (like https://linkedin.com/in/ACwAACaX8uYBfAh-5YxmfObz4mVOKYih3zxa-TM).

Authorizations

X-API-KEY
string
header
required

Your API key

Headers

Idempotency-Key
string

A unique value you generate per operation, such as a UUID. Retrying with the same key and the same body returns the stored response instead of running the request again, so a retry after a timeout never charges twice. Successful responses are kept for 24 hours; a failed request is not stored and can be retried with the same key.

Maximum string length: 255
Example:

"4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11"

Body

application/json

Lead search parameters

search_url
string<uri>

A LinkedIn Sales Navigator search URL (https://www.linkedin.com/sales/search/...). Any other URL is rejected with 422. Required unless persona_id is sent.

persona_id
string<uuid>

UUID of one of your personas. Its Sales Navigator search URL is used when search_url is omitted, and its name when name is omitted. An unknown UUID returns 404.

Example:

"3f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11"

webhook_url
string<uri>

Optional webhook URL to receive notifications when the search is complete

name
string

Name of the lead search. Defaults to a timestamped name when omitted.

streaming
boolean
default:false

When set to true, leads will be sent individually to the webhook_url as they are found. This is ideal for integration with platforms like Clay that process leads in real-time.

Example:

true

custom
object

Custom fields to include with the lead search that will be returned in the webhook (like crm id, etc.)

Example:
limit
integer

Maximum number of leads to return, from 1 to 2500; any other value returns 422. If omitted, every lead the search finds is returned, up to 2500.

Required range: 1 <= x <= 2500
Example:

100

scale
boolean
default:false

When set to true, increases request volume by omitting the following fields: connections_count, headline, and vanity LinkedIn profile URL. You will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL (e.g., https://www.linkedin.com/in/mathieu-brun-picard/).

Example:

true

position
enum<string>
default:end

Workspace key only. Where the search joins your workspace's lead search queue: end (default) behind the searches already waiting, start ahead of them. Any other value returns 422. Ignored with a personal key. See Lead search queue.

Available options:
end,
start
Example:

"start"

Response

Lead search created. Results will be delivered to webhook_url.

message
object
required
status_url
string<uri>
required

Where to poll the search: GET /searches/{id}. Same value as the Location header.

Example:

"https://app.pipecorn.com/api/v2/searches/8e1dcba0-f0bb-4071-99fc-f18ba6559ccc"