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

# Enrich a candidate with the Staplehire CLI

> Start a Staplehire candidate research job, poll it, and read candidate research from the CLI.

Use `candidates enrich` to start async candidate research, then poll the job and read results with `candidates research`.

```bash theme={null}
JOB_ID=$(staplehire candidates enrich <candidateId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"
staplehire candidates research <candidateId>
```

## Quickstart

```bash theme={null}
JOB_ID=$(staplehire candidates enrich <candidateId> \
  --prompt "Focus on backend systems, TypeScript, and startup experience." \
  | jq -r '.job.id')

staplehire jobs poll "$JOB_ID"
staplehire candidates research <candidateId>
```

Example enrich output:

```json theme={null}
{
  "job": {
    "id": "job_...",
    "type": "enrich",
    "status": "pending",
    "candidate_id": "cand_..."
  },
  "created": true
}
```

Example research output:

```json theme={null}
{
  "research": {
    "summary": "Candidate has recent backend platform experience.",
    "highlights": ["Built TypeScript services", "Worked in early-stage startups"],
    "sources": ["https://linkedin.com/in/..."]
  }
}
```

## Parameters

| Flag              | Required | Description                    |
| ----------------- | -------- | ------------------------------ |
| `<candidateId>`   | Yes      | Candidate to enrich            |
| `--prompt <text>` | No       | Extra research instructions    |
| `--force`         | No       | Start a fresh job when allowed |

## Examples

### Enrich and extract the summary

```bash theme={null}
JOB_ID=$(staplehire candidates enrich <candidateId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID" -q
staplehire candidates research <candidateId> | jq -r '.research.summary'
```

### Reuse an existing in-flight job

If the response has `"created": false`, a job is already running. Poll the returned `job.id`.

```bash theme={null}
JOB_ID=$(staplehire candidates enrich <candidateId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"
```

### Read screening results

```bash theme={null}
staplehire candidates screening-result <candidateId>
```

## Common errors

| Error                 | Cause                    | Fix                                            |
| --------------------- | ------------------------ | ---------------------------------------------- |
| `NotFoundError`       | Candidate does not exist | Run `candidates list` or `candidates get`      |
| Exit code `9`         | Poll timed out           | Increase `--timeout` or check `jobs get` later |
| `AuthenticationError` | Missing API key          | Run `staplehire login` or set `STAPLEHIRE_KEY` |

## FAQ

### Is candidate enrichment synchronous?

No. It creates a job. Poll it before calling `candidates research`.

### Can I customize the research focus?

Yes. Pass `--prompt` to `candidates enrich`.

### Where do I read the final research?

Call `staplehire candidates research <candidateId>` after the job reaches `done`.

Related: [Add a candidate with the Staplehire CLI](/docs/add-candidate-cli) · [Poll Staplehire CLI jobs](/docs/poll-agent-jobs) · [CLI errors](/docs/cli-errors)