> ## 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.

# Source candidates

> Start an AI sourcing job from the Staplehire CLI, poll the async job, and fetch matched prospects for a role as JSON.

`sourcing start` enqueues an AI sourcing job that finds prospects for a role. Like enrichment, it's **async**: start the job, [poll it](/docs/poll-agent-jobs), then list prospects with `sourcing prospects`.

```bash theme={null}
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

<Steps>
  <Step title="Start sourcing">
    ```bash theme={null}
    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')
    ```

    ```json theme={null}
    {
      "job": {
        "id": "job_…",
        "type": "source_role_prospects",
        "status": "pending",
        "role_id": "550e8400-e29b-41d4-a716-446655440000"
      },
      "created": true
    }
    ```
  </Step>

  <Step title="Poll until done">
    ```bash theme={null}
    staplehire jobs poll "$JOB_ID"
    ```
  </Step>

  <Step title="List the prospects">
    Always read prospects with `sourcing prospects` — not from the `jobs poll` output.

    ```bash theme={null}
    staplehire sourcing prospects "$ROLE_ID" | jq '.prospects[]'
    ```

    ```json theme={null}
    {
      "prospects": [
        {
          "name": "Jordan Lee",
          "email": "jordan@example.com",
          "linkedin_url": "https://linkedin.com/in/…",
          "fit_score": 0.82
        }
      ]
    }
    ```
  </Step>
</Steps>

### 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

```bash theme={null}
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.

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Does sourcing return results immediately?">
    No. Sourcing is asynchronous — poll the job, then call `sourcing prospects`.
  </Accordion>

  <Accordion title="Can I steer the search?">
    Yes. Pass `--prompt` to `sourcing start` to focus the sourcing job.
  </Accordion>

  <Accordion title="What is `sourcing list`?">
    A deprecated alias for `sourcing prospects`.
  </Accordion>
</AccordionGroup>

Related: [Create a role](/docs/create-role-cli) · [Poll jobs](/docs/poll-agent-jobs) · [CLI errors](/docs/cli-errors)