ashby-api-guide

# 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

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `candidate_create` | Create new candidate | name, email |
| `candidate_search` | Find by email/name | email or name |
| `candidate_list` | List all candidates | (optional) cursor, limit |
| `candidate_info` | Get candidate details | candidateId |
| `candidate_update` | Update candidate | candidateId |
| `candidate_add_note` | Add note to profile | candidateId, note |
| `candidate_add_tag` | Tag a candidate | candidateId, tagId |
| `candidate_list_notes` | View all notes | candidateId |

### Job Management

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `job_create` | Create new job | title |
| `job_search` | Find jobs | (optional) title, status |
| `job_list` | List all jobs | (optional) cursor, limit |
| `job_info` | Get job details | jobId |
| `job_set_status` | Update status | jobId, status |

Job statuses: `Open`, `Closed`, `Draft`, `Archived`

### Application Management

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `application_create` | Consider candidate for job | candidateId, jobId |
| `application_list` | List applications | (optional) jobId, candidateId, status |
| `application_info` | Get application details | applicationId |
| `application_change_stage` | Move in pipeline | applicationId, interviewStageId |
| `application_change_source` | Update attribution | applicationId, sourceId |
| `application_update` | Update properties | applicationId |

Application statuses: `Active`, `Hired`, `Archived`

### Interview Scheduling

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `interview_list` | List interviews | (optional) applicationId |
| `interview_schedule_create` | Schedule interview | applicationId, interviewerUserIds, startTime, endTime |
| `interview_schedule_list` | List schedules | (optional) startTimeAfter, startTimeBefore |
| `interview_schedule_update` | Modify schedule | interviewScheduleId |
| `interview_schedule_cancel` | Cancel interview | interviewScheduleId |

### Organization

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `user_list` | List team members | (optional) includeDeactivated |
| `user_search` | Find user | email or name |
| `department_list` | List departments | (optional) includeArchived |
| `location_list` | List locations | (optional) includeArchived |

### Offers

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `offer_create` | Create offer | applicationId |
| `offer_list` | List offers | (optional) applicationId |

### Utilities

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `interview_stage_list` | Get pipeline stages | (optional) jobId |
| `source_list` | Get candidate sources | (optional) cursor |
| `candidate_tag_list` | Get available tags | (optional) cursor |
| `archive_reason_list` | Get rejection reasons | none |

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

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

List operations include pagination:

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

Error responses:

```json
{
  "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:

| Code | Meaning |
|------|---------|
| `invalid_input` | Missing or malformed parameter |
| `not_found` | Resource doesn't exist |
| `unauthorized` | Permission denied |
| `rate_limited` | Too many requests |
| `already_exists` | Duplicate entry |

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