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

Job Management

Job statuses: Open, Closed, Draft, Archived

Application Management

Application statuses: Active, Hired, Archived

Interview Scheduling

Organization

Offers

Utilities

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:

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