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