## Overview

A process template defines the stages a candidate moves through during your hiring pipeline. Templates are written in YAML and consist of an ordered list of stages, each with a type, name, and optional configuration.

When you create a job posting and select a template, the stages are instantiated in order. Candidates progress through each stage sequentially — from application to offer.

## Basic Structure

```yaml
name: My Hiring Process
description: |
  A short description of this template.
  Supports **Markdown** formatting.

tags:
  - engineering
  - remote

stages:
  - type: application_form
    name: "Application"
    config:
      candidate_description: "Tell us about yourself."

  - type: live_interview
    name: "Interview"
    config:
      duration_minutes: 60

  - type: offer
    name: "Offer"
```

### Top-Level Keys

| Key | Required | Description |
|-----|----------|-------------|
| `stages` | Yes | Ordered list of stage definitions (at least one) |
| `name` | No | Template name (can also be set in the form field) |
| `description` | No | Markdown-formatted description of the process |
| `tags` | No | List of string tags for categorization |
| `candidate_data_fields` | No | Candidate metadata fields (see Candidate Data Fields below) |
| `quick_fields` | No | Legacy alias for `candidate_data_fields` (still supported) |

### Stage Keys

Every stage requires `name` and `type`. The optional `config` hash and `reviewers` list vary by stage type.

| Key | Required | Description |
|-----|----------|-------------|
| `name` | Yes | Display name for the stage |
| `type` | Yes | One of the 10 stage types listed below |
| `config` | No | Type-specific configuration options |
| `reviewers` | No | List of reviewer assignments |

## Stage Types Reference

### application_form

The entry point for candidates. Collects structured information via custom form fields. Optionally holds candidates in a screening state before advancing.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `screening_enabled` | boolean | false | Hold submissions for manual review before advancing |
| `screening_message` | string | — | Message shown to candidates while screening is active |
| `fields` | array | — | List of form field definitions (see below) |

**Form field options:**

| Key | Required | Type | Description |
|-----|----------|------|-------------|
| `name` | Yes | string | Field identifier |
| `type` | Yes | string | `text`, `textarea`, `file`, `url`, `select`, `checkbox`, `email`, `phone` |
| `required` | No | boolean | Whether the field must be filled |
| `label` | No | string | Display label (defaults to name) |
| `placeholder` | No | string | Placeholder text |
| `max_length` | No | integer | Maximum character count (min: 1) |
| `options` | No | array | Choices for `select` fields |

```yaml
- type: application_form
  name: "Application"
  config:
    candidate_description: "Tell us about yourself."
    screening_enabled: true
    screening_message: "We'll review your application shortly."
    fields:
      - name: resume
        type: file
        required: true
      - name: experience_level
        type: select
        required: true
        options:
          - "Junior (0-2 years)"
          - "Mid (2-5 years)"
          - "Senior (5+ years)"
      - name: cover_letter
        type: textarea
        required: false
        max_length: 500
```

### code_assignment

A take-home coding exercise. When GitHub is connected, a private repo is created from a template for each candidate. Includes deadline management.

> **Important:** The repository specified in `github_template` must be marked as a template on GitHub. See [GitHub Template Repository Setup](/docs/github-template-repository-setup) for requirements and setup instructions.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `github_template` | string | — | GitHub template repo (e.g. `org/hiring-assignment`) |
| `duration_days` | integer | — | Days allowed to complete (min: 1) |
| `estimated_hours` | string | — | Estimated effort (e.g. `"3-8"`) |

> **Compensation:** Payouts are configured per-stage in the stage settings UI, not in the template YAML. Any stage type can offer compensation. See [Candidate Payouts](/docs/candidate-payouts) for details.

```yaml
- type: code_assignment
  name: "Take-Home Assignment"
  config:
    candidate_description: "Complete a practical coding exercise."
    github_template: "mycompany/hiring-challenge"
    duration_days: 7
    estimated_hours: "3-6"
```

### portfolio_upload

Candidates upload work samples (design files, writing samples, etc.). Supports file type restrictions and upload limits.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `accept` | array | — | Allowed file extensions (e.g. `pdf`, `png`, `figma`) |
| `max_files` | integer | — | Maximum number of files (min: 1) |

```yaml
- type: portfolio_upload
  name: "Portfolio Review"
  config:
    candidate_description: "Share 3-5 examples of your best work."
    accept:
      - pdf
      - png
      - jpg
      - figma
    max_files: 5
```

### questionnaire

Written questions for candidates to respond to asynchronously. Useful for scenario-based screening in support, sales, or writing roles.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `questions` | array | — | List of question definitions |

**Question options:**

| Key | Required | Type | Description |
|-----|----------|------|-------------|
| `type` | Yes | string | Question category (e.g. `scenario`) |
| `prompt` | Yes | string | The question text |

```yaml
- type: questionnaire
  name: "Written Scenarios"
  config:
    candidate_description: "Respond to these real-world scenarios."
    questions:
      - type: scenario
        prompt: "A customer reports a billing error. Walk us through your response."
      - type: scenario
        prompt: "You discover a bug affecting 10% of users. What do you do?"
```

### video

Presents a video to candidates. Supports uploaded videos (via Mux) or embedded videos from external platforms.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `video_source_type` | string | — | `mux` (uploaded) or `oembed` (external embed) |
| `video_oembed_url` | string | — | URL for embedded video (when source is `oembed`) |
| `video_description` | string | — | Description or context for the video |
| `video_min_watch_percentage` | integer | — | Minimum watch percentage required (1-100) |

```yaml
- type: video
  name: "Company Introduction"
  config:
    candidate_description: "Watch this video about our team and culture."
    video_source_type: oembed
    video_oembed_url: "https://www.youtube.com/watch?v=example"
    video_description: "A 5-minute overview of our engineering team."
    video_min_watch_percentage: 80
```

### video_recording

Candidates record or upload a video response to a prompt. Useful for video introductions, video cover letters, or async video interviews. Requires Mux integration.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `max_duration_seconds` | integer | 120 | Maximum recording length in seconds |
| `allow_upload` | boolean | true | Allow candidates to upload a pre-recorded video file |
| `max_retakes` | integer | — | Number of re-recordings allowed (blank = unlimited) |

```yaml
- type: video_recording
  name: "Video Introduction"
  config:
    candidate_description: "Record a 2-minute video introducing yourself."
    max_duration_seconds: 120
    allow_upload: true
    max_retakes: 3
```

### team_review

An internal review stage where your team evaluates a candidate. Supports voting thresholds and veto rules.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Message shown to the candidate during this stage |
| `voting` | hash | — | Voting configuration (see below) |

**Voting options:**

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `threshold` | integer | — | Minimum yes votes to advance (1-10) |
| `require_all_reviewers` | boolean | false | All assigned reviewers must vote |
| `veto_auto_rejects` | boolean | false | A single veto automatically rejects the candidate |

```yaml
- type: team_review
  name: "Code Review"
  config:
    candidate_description: "Our team is reviewing your submission."
    voting:
      threshold: 2
      require_all_reviewers: true
      veto_auto_rejects: true
```

### live_interview

A synchronous interview conducted over video call or in person. Integrates with calendar scheduling.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `duration_minutes` | integer | — | Interview length in minutes (min: 15) |
| `interviewers_required` | integer | — | Number of interviewers needed (min: 1) |
| `includes_roleplay` | boolean | false | Whether the interview includes a role-play exercise |

```yaml
- type: live_interview
  name: "Technical Interview"
  config:
    candidate_description: "A conversation about your technical skills."
    duration_minutes: 60
    interviewers_required: 2
```

### reference_check

Collect and verify candidate references.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Instructions shown to the candidate |
| `references_required` | integer | — | Number of references needed (min: 1) |

```yaml
- type: reference_check
  name: "References"
  config:
    candidate_description: "Provide contact details for your references."
    references_required: 2
```

### offer

The final stage where you extend an offer to the candidate. Typically has minimal configuration.

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `candidate_description` | string | — | Message shown to the candidate |

```yaml
- type: offer
  name: "Offer"
  config:
    candidate_description: "We'd love to have you join the team."
```

## Reviewers

You can assign reviewers to any stage. Each reviewer needs an email address and a role.

| Key | Required | Description |
|-----|----------|-------------|
| `email` | Yes | Email address of the reviewer (must match a team member) |
| `role` | Yes | `reviewer` (standard) or `lead` (primary decision-maker) |

```yaml
- type: team_review
  name: "Code Review"
  config:
    voting:
      threshold: 2
  reviewers:
    - email: alice@company.com
      role: lead
    - email: bob@company.com
      role: reviewer
    - email: carol@company.com
      role: reviewer
```

## Candidate Data Fields

Candidate data fields define structured metadata that your team captures for each applicant — things like salary expectations, availability, location preference, or any custom signal relevant to your role. Fields appear in the candidate sidebar and can optionally be populated automatically by AI extraction from cover letters, resumes, and messages.

For managing field definitions directly in the UI, see [Candidate Data Fields](/docs/candidate-data-fields).

### Schema

| Key | Required | Type | Description |
|-----|----------|------|-------------|
| `key` | Yes | string | Unique identifier (lowercase, underscores only, e.g. `salary_expectation`) |
| `label` | Yes | string | Display label shown to your team |
| `field_type` | No | string | One of the 9 field types below (default: `text`) |
| `placeholder` | No | string | Placeholder text for the input |
| `required` | No | boolean | Whether the field must be filled before advancing |
| `options` | No | array | Choices for `select` fields |
| `ai_extractable` | No | boolean | Enable AI auto-population from candidate materials (default: `false`) |
| `ai_prompt` | No | string | Instruction for the AI extraction model. Required when `ai_extractable: true` |
| `visibility` | No | string | `everyone` (default) or `managers_only` — restrict who can see this field |

### Field Types

| Type | Description |
|------|-------------|
| `text` | Single-line text input |
| `textarea` | Multi-line text input |
| `number` | Numeric value |
| `date` | Date picker |
| `select` | Dropdown from a fixed list of choices |
| `boolean` | Yes/No toggle |
| `url` | URL input with link validation |
| `rating` | Numeric rating (default 1-5 stars) |
| `tags` | List of free-form string tags |

### Examples

Basic fields without AI extraction:

```yaml
candidate_data_fields:
  - key: salary_expectation
    label: "Salary Expectation"
    field_type: text
    placeholder: "$80,000 - $100,000"
  - key: start_date
    label: "Earliest Start Date"
    field_type: date
  - key: work_authorization
    label: "Work Authorization"
    field_type: select
    options:
      - "US Citizen"
      - "Permanent Resident"
      - "Requires Sponsorship"
```

Fields with AI extraction — the AI reads the candidate's application materials and populates these automatically:

```yaml
candidate_data_fields:
  - key: salary_expectation
    label: "Salary Expectation"
    field_type: text
    placeholder: "e.g. $120k - $150k"
    ai_extractable: true
    ai_prompt: "Extract the candidate's expected salary, compensation range, or rate. Return null if not mentioned."
  - key: availability
    label: "Availability / Start Date"
    field_type: text
    placeholder: "e.g. 2 weeks notice, April 2026"
    ai_extractable: true
    ai_prompt: "Extract when the candidate can start or their notice period. Return null if not mentioned."
  - key: location_preference
    label: "Location Preference"
    field_type: text
    ai_extractable: true
    ai_prompt: "Extract the candidate's location, city, country, or remote work preference."
  - key: source
    label: "Source / Referral"
    field_type: text
    placeholder: "e.g. LinkedIn, referral from..."
  - key: overall_rating
    label: "Overall Rating"
    field_type: rating
    visibility: managers_only
```

## Complete Example

A full template for hiring a software engineer, including screening, a code assignment, team review, two interview rounds, references, and an offer. To add compensation to the assignment stage, configure payouts in the stage settings UI — see [Candidate Payouts](/docs/candidate-payouts).

```yaml
name: Software Engineer - Standard
description: |
  Comprehensive process for mid-to-senior software engineers.
  Includes a take-home assignment with team code review.

tags:
  - engineering
  - technical
  - assignment

candidate_data_fields:
  - key: salary_expectation
    label: "Salary Expectation"
    field_type: text
    placeholder: "e.g. $120k - $150k"
    ai_extractable: true
    ai_prompt: "Extract the candidate's expected salary, compensation range, or rate. Return null if not mentioned."
  - key: notice_period
    label: "Notice Period"
    field_type: text
    ai_extractable: true
    ai_prompt: "Extract the candidate's notice period or earliest available start date. Return null if not mentioned."
  - key: location_preference
    label: "Location Preference"
    field_type: text
    ai_extractable: true
    ai_prompt: "Extract the candidate's location, city, country, or remote work preference."

stages:
  - type: application_form
    name: "Application"
    config:
      candidate_description: "Tell us about yourself and your experience."
      screening_enabled: true
      screening_message: "We're reviewing your application."
      fields:
        - name: resume
          type: file
          required: true
        - name: github_url
          type: url
          required: false
        - name: motivation
          type: textarea
          required: true
          max_length: 500

  - type: code_assignment
    name: "Take-Home Assignment"
    config:
      candidate_description: "Complete a practical coding exercise at your own pace."
      github_template: "mycompany/hiring-assignment"
      duration_days: 8
      estimated_hours: "3-8"
    reviewers:
      - email: tech-lead@company.com
        role: lead

  - type: team_review
    name: "Code Review"
    config:
      candidate_description: "Our team reviews your code submission."
      voting:
        threshold: 2
        require_all_reviewers: true
        veto_auto_rejects: true
    reviewers:
      - email: tech-lead@company.com
        role: lead
      - email: senior-dev@company.com
        role: reviewer

  - type: live_interview
    name: "Technical Interview"
    config:
      candidate_description: "A conversation about your technical skills."
      duration_minutes: 75
      interviewers_required: 2

  - type: live_interview
    name: "Culture & Values"
    config:
      candidate_description: "Get to know the team and learn about our culture."
      duration_minutes: 45
      interviewers_required: 1

  - type: reference_check
    name: "References"
    config:
      references_required: 2

  - type: offer
    name: "Offer"
    config:
      candidate_description: "We'll present you with an offer to join the team."
```

## Tips

- **Start with `application_form`** — it's the natural entry point and lets you collect resumes and basic info.
- **End with `offer`** — keeps the pipeline clean and gives you a final stage for tracking.
- **Use screening** on the application form to manually review candidates before they advance. This prevents unqualified candidates from receiving assignments.
- **Pay for take-home assignments** — configure payouts in the stage settings to compensate candidates. See [Candidate Payouts](/docs/candidate-payouts).
- **Keep processes under 7 stages** — long pipelines lead to candidate drop-off.
- **Assign reviewers** to team_review and code_assignment stages so the right people are notified automatically.
- **Use `candidate_description`** on every stage — candidates see this message, so clear communication reduces confusion and support requests.
- **Use AI extraction for common signals** — set `ai_extractable: true` with a clear `ai_prompt` on fields like salary expectation, availability, and location. The AI reads cover letters and application answers to pre-fill these automatically. See [Candidate Data Fields](/docs/candidate-data-fields).
- **Restrict sensitive fields with `visibility: managers_only`** — ratings, internal notes, or compensation benchmarks can be hidden from reviewers who don't need them.