Skip to main content

Documentation Index

Fetch the complete documentation index at: https://staplehire.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Start a sourcing job for a role, poll the async job, then list matched prospects as JSON. 
JOB_ID=$(staplehire sourcing start <roleId> --prompt "Backend engineers, seed-stage, remote" | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"
staplehire sourcing prospects <roleId>

​
Quickstart

Create a role first if you do not already have a roleId. 
ROLE_ID=$(staplehire roles create --jd "Senior backend engineer. TypeScript, remote." | jq -r '.role.id')
JOB_ID=$(staplehire sourcing start "$ROLE_ID" --prompt "Backend engineers, seed-stage, remote" | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"
staplehire sourcing prospects "$ROLE_ID" | jq '.prospects[]'
Example sourcing start output: 
{
  "job": {
    "id": "job_...",
    "type": "source_role_prospects",
    "status": "pending",
    "role_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "created": true
}
Example prospects output: 
{
  "prospects": [
    {
      "name": "Jordan Lee",
      "email": "jordan@example.com",
      "linkedin_url": "https://linkedin.com/in/...",
      "fit_score": 0.82
    }
  ]
}

​
Parameters

CommandParameterRequiredDescription
sourcing start<roleId>YesRole to source against
sourcing start--prompt <text>NoExtra sourcing instructions
sourcing start--forceNoStart a fresh job when allowed
sourcing prospects<roleId>YesRole whose prospects should be listed

​
Examples

​
Source remote backend engineers

staplehire sourcing start <roleId> --prompt "Backend engineers, seed-stage, remote"

​
Source candidates and keep only strong fits

staplehire sourcing prospects <roleId> | jq '.prospects[] | select(.fit_score >= 0.8)'

​
Avoid duplicate sourcing jobs

If created is false, a job is already in flight. Poll the returned job.id instead of starting another job. 
JOB_ID=$(staplehire sourcing start <roleId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"

​
Common errors

ErrorCauseFix
NotFoundErrorThe role ID does not existRun staplehire roles list and use a real role ID
AuthenticationErrorNo API key is configuredRun staplehire login or set STAPLEHIRE_KEY
Exit code 9Poll timed outIncrease --timeout or check the job later

​
FAQ

​
Does sourcing return results immediately?

No. Sourcing is async. Call jobs poll before reading prospects.

​
Can I source with a custom prompt?

Yes. Pass --prompt to sourcing start.

​
What is sourcing list?

It is an alias for sourcing prospects. Related: Create a role with the Staplehire CLI · Poll Staplehire CLI jobs · CLI errors