Ashby API Guide

Reference guide for working with the Ashby ATS integration. This skill covers authentication, available tools, and common usage patterns.

Overview

The Ashby plugin provides ~30 MCP tools for interacting with Ashby's Applicant Tracking System (ATS). All operations use Ashby's RPC-style API where every endpoint accepts POST requests.

Authentication

Ashby uses Basic Authentication with an API key:

1. Generate an API key in Ashby: Settings → API Keys
2. Set the environment variable:

   ASHBY_API_KEY=your-api-key

3. The MCP server handles authentication automatically

API keys have permission scopes. Common permissions needed:

• candidatesRead

  /

  candidatesWrite

  - Candidate operations

• jobsRead

  /

  jobsWrite

  - Job operations

• interviewsWrite

  - Interview scheduling

Available Tools

Candidate Management

candidate_create

candidate_search

candidate_list

candidate_info

candidate_update

candidate_add_note

candidate_add_tag

candidate_list_notes

Job Management

job_create

job_search

job_list

job_info

job_set_status

Job statuses:

Open

Closed

Draft

Archived

Application Management

application_create

application_list

application_info

application_change_stage

application_change_source

application_update

Application statuses:

Active

Hired

Archived

Interview Scheduling

interview_list

interview_schedule_create

interview_schedule_list

interview_schedule_update

interview_schedule_cancel

Organization

user_list

user_search

department_list

location_list

Offers

offer_create

offer_list

Utilities

interview_stage_list

source_list

candidate_tag_list

archive_reason_list

Common Operations

Find a Candidate

# By email (exact match)
candidate_search(email="jane@example.com")

# By name (partial match)
candidate_search(name="Jane")

Create and Apply Candidate

# Step 1: Create candidate
candidate = candidate_create(
    name="Jane Smith",
    email="jane@example.com"
)

# Step 2: Apply to job
application_create(
    candidateId=candidate["id"],
    jobId="target-job-id"
)

Move Candidate Through Pipeline

# Get current stage and next stage
stages = interview_stage_list(jobId="...")
next_stage_id = stages["results"][1]["id"]

# Move application
application_change_stage(
    applicationId="app-id",
    interviewStageId=next_stage_id
)

Schedule an Interview

interview_schedule_create(
    applicationId="app-id",
    interviewerUserIds=["user-1", "user-2"],
    startTime="2024-01-15T14:00:00Z",
    endTime="2024-01-15T15:00:00Z"
)

Reject a Candidate

# Get archive reasons
reasons = archive_reason_list()
reason_id = reasons["results"][0]["id"]  # e.g., "Not qualified"

# Get archived stage
stages = interview_stage_list(jobId="...")
archived_stage = next(s for s in stages["results"] if s["type"] == "Archived")

# Archive
application_change_stage(
    applicationId="app-id",
    interviewStageId=archived_stage["id"],
    archiveReasonId=reason_id
)

Response Format

All tools return JSON. Successful responses have this structure:

{
  "success": true,
  "results": { ... }  // or array for list operations
}

List operations include pagination:

{
  "success": true,
  "results": [...],
  "moreDataAvailable": true,
  "nextCursor": "cursor-string"
}

Error responses:

{
  "success": false,
  "errors": ["error_code"]
}

Pagination

List operations use cursor-based pagination:

# First page
results = candidate_list(limit=50)

# Next page (if moreDataAvailable is true)
results = candidate_list(limit=50, cursor=results["nextCursor"])

Date/Time Format

All timestamps use ISO 8601 format:

• 2024-01-15T14:00:00Z

  (UTC)

• 2024-01-15T14:00:00-08:00

  (with offset)

Error Codes

Common error codes and meanings:

invalid_input

not_found

unauthorized

rate_limited

already_exists

Tips

Finding IDs

Most operations require resource IDs. Use search/list tools first:

# Get candidate ID
candidate = candidate_search(email="...")["results"][0]
candidate_id = candidate["id"]

# Get job ID
job = job_search(title="...")["results"][0]
job_id = job["id"]

Filtering Applications

Filter by multiple criteria:

# All active apps for a specific job
application_list(jobId="...", status="Active")

# All apps for a specific candidate
application_list(candidateId="...")

Source Attribution

Always track where candidates come from:

# Get available sources
sources = source_list()

# Apply with source
application_create(
    candidateId="...",
    jobId="...",
    sourceId="linkedin-source-id"
)

Additional Resources

Reference Files

For complete API patterns:

• references/tool-reference.md

  - Full parameter details for all tools

Related Skills

• ashby-workflows - Pipeline management and recruiting workflows