Source candidates

sourcing start enqueues an AI sourcing job that finds prospects for a role. Like enrichment, it’s async: start the job, poll it, then list prospects with sourcing prospects.

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>

The start → poll → list pattern

Start sourcing

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')

{
  "job": {
    "id": "job_…",
    "type": "source_role_prospects",
    "status": "pending",
    "role_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "created": true
}

Poll until done

staplehire jobs poll "$JOB_ID"

List the prospects

Always read prospects with sourcing prospects — not from the jobs poll output.

staplehire sourcing prospects "$ROLE_ID" | jq '.prospects[]'

{
  "prospects": [
    {
      "name": "Jordan Lee",
      "email": "jordan@example.com",
      "linkedin_url": "https://linkedin.com/in/…",
      "fit_score": 0.82
    }
  ]
}

Parameters

Command	Parameter	Required	Description
`sourcing start`	`<roleId>`	Yes	Role to source against
`sourcing start`	`--prompt <text>`	No	Extra sourcing instructions
`sourcing start`	`--force`	No	Start a fresh job even if one is in flight
`sourcing prospects`	`<roleId>`	Yes	Role whose prospects to list (alias: `sourcing list`)

Examples

Keep only strong fits

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

Avoid duplicate sourcing jobs

If created is false, a sourcing job is already running for the role. Poll the returned job.id instead of starting another.

RESP=$(staplehire sourcing start <roleId>)
[ "$(echo "$RESP" | jq -r '.created')" = "false" ] && echo "Reusing in-flight job"
staplehire jobs poll "$(echo "$RESP" | jq -r '.job.id')"

Common errors

Error	Exit code	Fix
`NotFoundError`	`4`	The role ID does not exist — run `staplehire roles list`
Poll timeout	`9`	Increase `--timeout` or check the job later with `jobs get`
`job_failed`	`1`	Read `error.message`; adjust the prompt and retry with `--force`
`AuthenticationError`	`2`	Run `staplehire login` or set `STAPLEHIRE_KEY`

FAQ

Does sourcing return results immediately?

No. Sourcing is asynchronous — poll the job, then call sourcing prospects.

Can I steer the search?

Yes. Pass --prompt to sourcing start to focus the sourcing job.

What is `sourcing list`?

A deprecated alias for sourcing prospects.

Related: Create a role · Poll jobs · CLI errors

Get started

Workflows

Automation

Reference

The start → poll → list pattern

Parameters

Examples

Keep only strong fits

Avoid duplicate sourcing jobs

Common errors

FAQ

​The start → poll → list pattern

​Parameters

​Examples

​Keep only strong fits

​Avoid duplicate sourcing jobs

​Common errors

​FAQ

The start → poll → list pattern

Parameters

Examples

Keep only strong fits

Avoid duplicate sourcing jobs

Common errors

FAQ