Skip to main content
POST
/
sourcing
/
preview
Initiate sourcing preview run
curl --request POST \
  --url https://api.instaview.sk/sourcing/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Senior Backend Engineers – FinTech",
  "jobDescription": "We are looking for a Senior Backend Engineer with 5+ years of Node.js experience…",
  "location": "San Francisco, CA",
  "query": "Senior Node.js engineer fintech",
  "limit": 20,
  "webhookId": "123e4567-e89b-12d3-a456-426614174000"
}
'
{
  "success": true,
  "requestId": "req_550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Sourcing run accepted and queued for processing.",
  "webhookId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:01:00.000Z"
}
Starts an asynchronous candidate sourcing preview pipeline. Returns immediately with a requestId and status: "processing".

​
Overview

The preview endpoint allows you to rapidly run candidate searches and obtain preview results. Under the hood, it queries the underlying provider’s search preview API.

​
Key Differences from Standard Sourcing

  • No Deep Enrichment: Preview results do not include deep profile enrichment (like contact details, emails, work history, fit points, or red flags).
  • Fast Execution: Responses are prepared quickly (usually in a few milliseconds to seconds).
  • Stripped-down Candidate DTO: Candidates in the results only contain 9 basic fields (listed below).
  • Credit Cost: Candidate previews charge 1 credit (or 0.4 minutes) per preview page successfully queried (where each page contains up to 20 candidates).

​
Candidate Limits and Internal Pagination

The preview API automatically handles pagination internally based on the number of candidates you request:
  • Use the optional limit parameter to specify the desired candidate count (between 1 and 100, default: 20).
  • The system automatically polls the underlying provider’s preview pages sequentially (up to 5 pages of 20 results each) to satisfy your requested limit.
  • Previews are charged per page queried (1 credit / 0.4 minutes per page). For example, requesting a limit of 40 candidates queries up to 2 pages, costing up to 2 credits.
Results are delivered via webhooks (recommended) or by polling GET /sourcing/preview//results.

​
Billing and Pre-Flight

Candidate previews charge 1 credit (or 0.4 minutes) per preview page successfully queried. At initialization, a pre-flight balance check is performed for the maximum possible cost based on the requested limit (computed as Math.ceil(limit / 20) * 1 credit). If the company does not have sufficient credits or minutes, the request is rejected with a 402 Payment Required status. During execution, if the provider returns fewer pages than requested (e.g. because results are exhausted), only the pages successfully queried are charged, and any unused credits from the initial hold are automatically released.

​
Webhook Delivery

To receive results without polling, pass a webhookId referencing a pre-registered WebhookConfig that subscribes to at least one of SOURCING_COMPLETED or SOURCING_FAILED. The webhook config must belong to the same company as the authenticating API key. When the preview run completes, a SOURCING_COMPLETED webhook event is dispatched. The candidates array in the webhook payload will contain preview-formatted candidates containing only the 9 basic fields.
See Setting Up Webhooks for instructions on registering a webhook config and storing the signing secret securely.

​
Examples

​
Minimal Request

{
  "title": "Senior Backend Engineer",
  "jobDescription": "We are looking for a Senior Backend Engineer with 5+ years of Node.js and TypeScript experience, strong PostgreSQL skills, and familiarity with AWS."
}

​
Full Request with Candidate Limit

{
  "title": "Senior Staff ML Engineer",
  "jobDescription": "We are seeking a Staff Machine Learning Engineer to design and scale our agentic coding infrastructure. Experience with prompt engineering pipelines, LLM fine-tuning, vector search, and latency optimization is highly required.",
  "location": "Remote, USA",
  "query": "Prioritize candidates with active contributions to major LLM libraries or frameworks like LangChain, LlamaIndex, or vLLM.",
  "webhookId": "3f9a12c7-44b8-4d32-b71f-e29a7d1e0f5c",
  "limit": 50
}

​
Response (202 Accepted)

{
  "success": true,
  "requestId": "req_prev_9f3b827e-8c31-4bda-a7a2-b2d99d14f4e2",
  "status": "processing",
  "message": "Sourcing preview run accepted and queued for processing.",
  "webhookId": "3f9a12c7-44b8-4d32-b71f-e29a7d1e0f5c",
  "createdAt": "2026-06-11T19:50:45.000Z"
}

​
Preview Candidate Fields

The candidates array returned for preview requests (both from the polling endpoint and webhook) is stripped down to exactly the following 9 fields:
  • profileId (Opaque identifier, MD5 hash of LinkedIn profile URL)
  • fullName
  • profileUrl
  • title
  • headline
  • location
  • country
  • companyName
  • companyUrl

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Body

application/json
​
title
string
required

Human-readable title for this sourcing run.

Maximum string length: 200
Example:

"Senior Backend Engineers – FinTech"

​
jobDescription
string
required

Full job description used to build the candidate-search query.

Maximum string length: 10000
Example:

"We are looking for a Senior Backend Engineer with 5+ years of Node.js experience…"

​
location
string

Target location for the search (e.g. 'San Francisco, CA' or 'Remote').

Maximum string length: 200
Example:

"San Francisco, CA"

​
query
string

Override for the free-text search query sent to the sourcing agent. When omitted the agent derives it from jobDescription.

Maximum string length: 500
Example:

"Senior Node.js engineer fintech"

​
limit
integer
default:20

Maximum number of candidates to return (default: 20, max: 100).

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

20

​
webhookId
string<uuid>

UUID of a WebhookConfig to notify when the run completes or fails. The webhook must belong to the same company and subscribe to at least one sourcing event.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Sourcing preview run accepted and queued for processing

​
success
boolean
required

Whether the request was accepted for processing.

Example:

true

​
requestId
string
required

Unique external identifier for this sourcing run.

Example:

"req_550e8400-e29b-41d4-a716-446655440000"

​
status
enum<string>
required

Current status of the run.

Available options:
processing,
completed,
failed
Example:

"processing"

​
message
string
required

Human-readable message.

Example:

"Sourcing run accepted and queued for processing."

​
webhookId
string

UUID of the webhook configuration that will receive completion events.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
createdAt
string

ISO 8601 timestamp when the run was created (POST only).

Example:

"2025-01-01T00:00:00.000Z"

​
updatedAt
string

ISO 8601 timestamp when the run was last updated (PATCH only).

Example:

"2025-01-01T00:01:00.000Z"