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.

Add a candidate to a role with candidates create. The command is idempotent per role and email. 
staplehire candidates create <roleId> --email alex@company.com --name "Alex Chen"

​
Quickstart

staplehire candidates create 550e8400-e29b-41d4-a716-446655440000 \
  --email alex@company.com \
  --name "Alex Chen"
Example output: 
{
  "candidate": {
    "id": "cand_...",
    "email": "alex@company.com",
    "name": "Alex Chen",
    "role_id": "550e8400-e29b-41d4-a716-446655440000",
    "stage_id": "stage_..."
  }
}
Extract the candidate ID: 
CANDIDATE_ID=$(staplehire candidates create <roleId> --email alex@company.com --name "Alex Chen" | jq -r '.candidate.id')

​
Parameters

FlagRequiredDescription
<roleId>YesRole to add the candidate to
--email <email>YesCandidate email address
--name <name>NoDisplay name
--stage-id <id>NoPipeline stage ID
--stage <name>NoStage name resolved on the role
--phoneNoCandidate phone number
--linkedin-urlNoLinkedIn profile URL
--portfolio-urlNoPortfolio URL
--current-locationNoCandidate location

​
Examples

​
Add a candidate to a named stage

staplehire candidates create <roleId> \
  --email alex@company.com \
  --name "Alex Chen" \
  --stage "Applied"

staplehire candidates create <roleId> \
  --email alex@company.com \
  --name "Alex Chen" \
  --linkedin-url https://linkedin.com/in/alexchen \
  --portfolio-url https://alex.dev

​
Move a candidate to a new stage

staplehire candidates move <candidateId> --stage-id <stageId>

​
Read candidates

staplehire candidates list --role-id <roleId>
staplehire candidates get <candidateId>
staplehire candidates screening-result <candidateId>

​
Common errors

ErrorCauseFix
ValidationErrorInvalid email or missing required flagPass a valid --email and role ID
ConflictErrorDuplicate candidate on the roleFetch the existing candidate instead of creating another
NotFoundErrorRole or stage does not existRun roles list or stages list <roleId>

​
FAQ

​
Can I add the same email twice?

The command is idempotent per role and email. If the API returns a conflict, read the existing candidate.

​
Should I use --stage or --stage-id?

Use --stage-id when you have the ID. Use --stage when you want the CLI to resolve a stage name on the role.

​
What is the alias for candidates create?

add is an alias. Related: Create a role with the Staplehire CLI · Enrich a candidate with the Staplehire CLI · Send an interview with the Staplehire CLI