AI sourcing and recruiting agent for LinkedIn and the open web

Piiple Candidate Pack API is an AI candidate sourcing and recruiting agent API. Its AI recruiting agent searches LinkedIn, recruitment platforms, and the open web to find professional profiles and evaluate them against your hiring criteria.

Define the job titles, locations, target companies, skills, and requirements that matter to your search. Receive structured candidate profiles with profile links, evaluation scores, and reasons for qualification or elimination. Recruiters, talent acquisition teams, and developers can use these results to review potential hires and build candidate shortlists.

You do not need a separate Piiple account or API key. Each run saves all completed candidate evaluations to the default Apify Dataset and a job summary to the key-value store's OUTPUT record.

Candidate sourcing and screening features

• Find candidates by hiring criteria: search by role, location, skills, and target employers.
• Evaluate candidate fit: assess profiles against your must-have and nice-to-have requirements.
• Review the reasoning: see qualification or elimination reasons, evaluation scores, and missing evidence.
• Access all completed evaluations: review both qualified and eliminated profiles in the Dataset.
• Find more candidates: continue a completed search using its Piiple job ID and saved filters. This works only for jobs created by this Actor under the same Apify account.
• Track search outcomes: check evaluated candidate counts, qualified candidate counts, issues, and completion details in OUTPUT.

Recruiting use cases

LinkedIn candidate search by role and skills

Find professional profiles for a specific hiring need, such as backend engineers in Istanbul with Node.js and PostgreSQL experience. Review how each evaluated profile matches your requirements.

Talent sourcing from target companies

Focus your candidate search on target employers, required previous companies, industry, or company size. Combine employer filters with role and location criteria to define the talent pool you want to search.

Open web recruiting and candidate evaluation

Discover professionals across recruitment platforms and the open web, then use the completed evaluations to build a shortlist. Review the available profile evidence and the reasons each candidate qualifies or is eliminated.

How to find candidates with Piiple

1. Define your ideal candidate profile, or ICP, using roles, locations, skills, and hiring requirements.
2. Set scan_limit to the maximum number of candidates you want evaluated, from 1 to 1000, and ensure the Apify run spending limit covers the requested candidate evaluations.
3. Run the Actor and review the default Dataset. Filter evaluation.status by qualified to see matching candidates.
4. Check OUTPUT for search counts and outcome details. To continue a completed search, use its jobId in a Find more run.

Input

For a new search, provide icp and scan_limit. The example below is illustrative and contains no real candidate data.

{
  "icp": {
    "roles": ["Backend Engineer", "Software Engineer"],
    "role_scope": "current_only",
    "locations": [
      { "country_code": "TR", "city": "Istanbul" }
    ],
    "target_companies": [],
    "company_scope": "current_only",
    "skills": ["Node.js", "PostgreSQL"],
    "must_haves": [
      { "id": "production-backend", "text": "Professional experience building production backend systems" }
    ],
    "nice_to_haves": []
  },
  "scan_limit": 10
}

scan_limit is the maximum number of candidates to evaluate, not the number of qualified candidates guaranteed to be returned. The Actor input accepts values from 1 to 1000; some evaluation attempts may fail, so the completed and billable total can be lower. The technical field remains named scan_limit. Search results depend on the criteria and available profile evidence; a successful run may return fewer candidates or no matches.

Use these optional filters to refine your candidate search:

ICP field	Meaning
past_job_titles	Required prior-role alternatives, in addition to the main role requirement.
required_past_companies	Required prior-employer alternatives; entries accept name and/or linkedin_url.
current_company_tenure	Current-company tenure bounds, e.g. { "min_years": 2, "max_years": 5 }.
minimum_role_duration_months	Minimum average tenure across merged employment stints, in months.
company_industries	Employer industry constraints.
company_headcount_ids	Current-employer size buckets: A self-employed, B 1–10, C 11–50, D 51–200, E 201–500, F 501–1,000, G 1,001–5,000, H 5,001–10,000, I 10,001+.
recently_changed_jobs	Set to true to search for people who changed their current role in the last 90 days.
exclusions	Describe profiles or characteristics to exclude from your search.

All these fields are optional. Use clear company names and requirements; if a company or requirement cannot be resolved, you may need to revise your input. Find more preserves your saved filters.

Find more candidates

After a completed run, copy its jobId from OUTPUT and start another run with that ID and a new candidate evaluation limit. The saved ICP is reused; you do not need to send it again.

{
  "parent_job_id": "00000000-0000-4000-8000-000000000000",
  "scan_limit": 10
}

Each Find more run is a separate search. Review the price shown by Apify before starting it.

Results

Profile photos are archived to Piiple storage when possible. If a photo cannot be archived, its original source URL is retained; photo storage failures do not fail the candidate search. Existing saved results are not backfilled.

New evaluations also include profile_image_url, experience[] (all available jobs, including simultaneous current positions), education[], and total_experience_months. Employment records include title, company, LinkedIn company URL, partial start/end dates, current status and duration in months. Education records include school, LinkedIn school URL, degree, field of study and partial dates. Dates use {year, month, day}; unknown parts remain null. Current roles have a null end date. Job durations are inclusive calendar months and remain null without sufficient date evidence or for reversed date ranges. duration_text preserves the original provider duration label separately, even when numeric duration cannot be calculated. Total experience uses the shared non-overlapping career calculation; partial source dates follow that calculation's conventions. Missing histories are empty arrays and unavailable values are null. Previously saved results may omit these added fields. Existing fields and evaluation/billing semantics are unchanged.

The default Dataset contains one item per completed billable candidate evaluation, including eliminated profiles. evaluation.status is qualified, rejected, or insufficient_evidence; the last two are eliminated outcomes. evaluation.summary explains the outcome, evaluation.criteria contains assessed requirements, and evaluation.missing_evidence identifies required criteria without sufficient evidence. Filter by qualified to see matching candidates only. Typical profile fields include full_name, linkedin_url, headline, location, current_position, total_experience_years, and provenance.

For example, 10 completed billable evaluations can produce 3 qualified and 7 eliminated profiles: all 10 are accessible in the Dataset. Technical failures and candidates skipped before evaluation are not billed as completed evaluations.

The OUTPUT key-value record contains status, candidate evaluation limits, counters, outcome, issues, and a support reference. returnedCount counts qualified candidates; exportedProfileCount counts all exported evaluations. rejectedCount and insufficientEvidenceCount report eliminated outcomes. Cancelled and failed runs may contain completed evaluations as partial output; failed runs retain their error status. Evaluated candidates are delivered and billed progressively while the Actor runs. After abrupt termination, evaluated candidates already written remain in the Dataset. Resurrect the same run to recover any remaining results.

Example OUTPUT record (illustrative):

{
  "status": "completed",
  "jobId": "00000000-0000-4000-8000-000000000000",
  "requestedScanLimit": 10,
  "effectiveScanLimit": 10,
  "partial": false,
  "returnedCount": 3,
  "exportedProfileCount": 10,
  "scannedCount": 10,
  "qualifiedCount": 3,
  "rejectedCount": 6,
  "insufficientEvidenceCount": 1,
  "chainTotals": {
    "scanned_count": 10,
    "enriched_count": 10,
    "rejected_count": 6,
    "qualified_count": 3,
    "discovered_count": 25,
    "enrichment_failed_count": 0,
    "evaluation_failed_count": 0,
    "evaluation_completed_count": 10,
    "insufficient_evidence_count": 1
  },
  "outcome": {
    "coverage": "limited",
    "stop_reason": "scan_limit_reached",
    "match_outcome": "matches_found",
    "warning_codes": [],
    "scan_completion": "complete"
  },
  "issues": [],
  "supportReference": null,
  "completedAt": "2026-10-16T07:00:00.000Z",
  "billing": {
    "provider": "Apify",
    "eventName": "candidate-scan",
    "status": "settled",
    "billableScanCount": 10,
    "chargedEventCount": 10
  }
}

Example Dataset item (illustrative; nested values depend on available evidence):

{
  "id": "example-candidate-id",
  "full_name": "Example Candidate",
  "linkedin_url": "https://example.invalid/profile",
  "headline": "Backend Engineer",
  "location": { "city": "Istanbul", "country_code": "TR" },
  "current_position": { "title": "Backend Engineer", "company_name": "Example Company" },
  "total_experience_years": 5,
  "evaluation": {
    "status": "qualified",
    "score": 90,
    "summary": "The profile matches the backend role and provides evidence of production backend development.",
    "criteria": [
      {
        "id": "icp.target_role",
        "kind": "required",
        "source": "model",
        "status": "passed",
        "evidence_summary": "The current Backend Engineer title matches the requested role."
      }
    ],
    "missing_evidence": []
  },
  "provenance": {},
  "piiple_job_id": "00000000-0000-4000-8000-000000000000"
}

Price per evaluated candidate

The price per evaluated candidate depends on your Apify subscription plan:

Apify plan	Price per evaluated candidate	Price per 1,000 evaluated candidates
Free	$0.060	$60.00
Starter (Bronze)	$0.060	$60.00
Scale (Silver)	$0.058	$58.00
Business (Gold)	$0.056	$56.00

You pay for each completed candidate evaluation, including candidates who do not qualify (rejected or insufficient_evidence). Unfinished or failed evaluations are not charged. Apify platform usage is included in the customer price. Unused evaluation budget is not charged; a completed search with no qualified matches may still have billable evaluated candidates. For example, 10 completed evaluations cost $0.60 on Free/Starter, $0.58 on Scale, or $0.56 on Business, even if only 3 profiles qualify. Review the applicable price shown by Apify before starting a run.

The run spending limit must cover the entire requested scan_limit at your plan's price per evaluated candidate. Otherwise, the Actor fails before starting a Piiple job; it never silently lowers your requested candidate evaluation limit. Increase the run spending limit or explicitly lower scan_limit to retry. For example, scan_limit: 1000 requires a $60 event budget on Free/Starter, $58 on Scale, or $56 on Business. This check uses the Apify run spending limit, not a direct query of your account credit balance; Apify controls account-level credit availability.

Completed candidate evaluations are written to the Dataset before their evaluation charge is recorded, including eliminated profiles. Charges are recorded progressively as evaluations are delivered. If the search later fails or is cancelled, completed billable work is still charged; unfinished or failed evaluations are not. A job with zero completed candidate evaluations has no evaluation charge.

On resurrection, the Actor checks previously confirmed charges against delivered evaluated candidates to avoid charging the same work twice. If a previous charge outcome cannot be verified, it stops further charging and writes a BILLING_RECONCILIATION_REQUIRED record for recovery. Without resurrection, an abrupt stop may leave the last completed evaluations undelivered and uncharged.

Frequently asked questions

Does Piiple find candidates on LinkedIn and the open web

Yes. Piiple's AI sourcing agent searches LinkedIn, recruitment platforms, and the open web for professional profiles relevant to your hiring criteria. Source coverage and returned profile details depend on available evidence.

Do I need a separate Piiple account or API key

No. You can run this Actor through Apify without a separate Piiple account or Piiple API key.

Does the Dataset include candidates who do not qualify

Yes. The Dataset includes all completed billable candidate evaluations, including rejected profiles and profiles with insufficient evidence. Filter evaluation.status by qualified to create your shortlist.

Does Piiple find email addresses or send recruiting messages

This Actor sources and evaluates candidates. It does not find or verify email addresses or phone numbers, send messages, or perform outreach.

Why can a search return fewer qualified candidates than the evaluation limit

scan_limit limits the number of candidates submitted for evaluation. It does not guarantee a number of qualified candidates. Results depend on your requirements and the available profile evidence; a successful run may return fewer candidates or no qualified matches.

Failed runs

Handled errors write status: "failed" and an error object to OUTPUT, with code, message, stage and action. API validation errors also include field details and httpStatus. Previously delivered profiles remain in the Dataset; existing counters, issues and billing information are preserved. backendStatus describes the last known Piiple job status, separately from the failed Actor operation.

jobStarted is false when no job was started, true when a job is known, and null when the creation request outcome could not be confirmed. For an unknown creation outcome or delivery/billing interruption, keep the same run and use Resurrect as instructed in error.action; starting a new run can create a separate sourcing job. Billing with status: "reconciliation_required" needs recovery, and chargedEventCount is the last confirmed checkpoint, not a fresh charge verification.

If Apify terminates the process abruptly, or its storage is unavailable, the Actor may be unable to save a new error record. Check the run Log and keep the run storage for recovery.

Insufficient run budget produces a failed run and a machine-readable OUTPUT record in the default key-value store:

{
  "status": "failed",
  "jobStarted": false,
  "requestedScanLimit": 1000,
  "effectiveScanLimit": 0,
  "error": {
    "code": "INSUFFICIENT_RUN_BUDGET",
    "message": "The Apify run spending limit does not cover the requested 1000 candidate evaluations. Increase the run spending limit or explicitly lower scan_limit and try again. No Piiple job was started.",
    "requestedScanLimit": 1000,
    "affordableScanCount": 500
  }
}

The output schema's Piiple job summary link points to this record. API clients can retrieve OUTPUT from the run's defaultKeyValueStoreId after the run fails. affordableScanCount reflects the run spending limit; it is not the account credit balance (and is null if the SDK cannot provide a finite count). No sourcing job or evaluation charge is created for this failure.

Privacy and support

Use candidate data only for lawful recruiting purposes and follow applicable privacy and platform rules. The example input above is synthetic. For help, include the Apify run ID and the supportReference from OUTPUT; do not include API keys or other secrets in support requests.