VX Agents

API directory · HR

Ashby Candidates & Applications

v1.0.0 · 18 endpoints · 0 connections · shared by vx.ai

Where does each candidate stand, and what did the interviewers say? Search Ashby candidates by name or email, read their applications, stage history and scorecards, see upcoming interview schedules, then add a note, tag a candidate or move an application to the next interview stage.

Connect this API to an AI agent Browse all specs

What you can do with Ashby Candidates & Applications via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
POST /candidate.search searchCandidates Find candidates by email and/or name
POST /candidate.info getCandidate Get a candidate's profile, contact details, tags and application ids
POST /candidate.listNotes listCandidateNotes List the notes on a candidate, newest first
POST /application.list listApplications List applications, filtered by job, status or creation date
POST /application.info getApplication Get an application with its job, current stage, source and status
POST /application.listHistory listApplicationHistory See every stage an application has passed through and when
POST /applicationFeedback.list listApplicationFeedback Read the interview scorecards and feedback on an application
POST /job.list listJobs List jobs, optionally only open ones
POST /job.info getJob Get a job with its hiring team, locations and interview plan
POST /interviewStage.list listInterviewStages List the stages of an interview plan in order
POST /interviewSchedule.list listInterviewSchedules List scheduled interviews and their events
POST /candidateTag.list listCandidateTags List the candidate tags in use
POST /archiveReason.list listArchiveReasons List the reasons an application can be archived (rejected, withdrew...)
POST /source.list listSources List candidate sources (referral, LinkedIn, job board...)
POST /candidate.createNote createCandidateNote Add a note to a candidate's profile
POST /candidate.addTag addCandidateTag Tag a candidate
POST /candidate.create createCandidate Create a new candidate with name, email, phone and links
POST /application.changeStage changeApplicationStage Move an application to another interview stage (or archive it with a reason)

Authentication

BasicAuth

HTTP Basic

HTTP basic auth with your Ashby API key as the username and an empty password (-u API_KEY:).

How to get a credential

  1. As an Ashby Admin, open Admin > Integrations > API Keys (app.ashbyhq.com/admin/api/credentials).
  2. Create a new key and name it (e.g. VX Agents recruiting).
  3. Grant the module permissions below; leave confidential jobs and private fields off unless needed.
  4. Copy the key (it is shown once).

Permissions used

Permission Operations
candidatesRead searchCandidates, getCandidate, listCandidateNotes, listApplications, getApplication, listApplicationHistory, listApplicationFeedback
candidatesWrite createCandidate, createCandidateNote, addCandidateTag, changeApplicationStage
hiringProcessMetadataRead listCandidateTags, listArchiveReasons, listSources
jobsRead listJobs, getJob
interviewsRead listInterviewStages, listInterviewSchedules

Common errors

Status Meaning Fix
401 API key missing Store the key as the basic-auth username with an empty password.
403 Key wrong or deactivated, or missing_endpoint_permission Check the key is active and grant the module permission listed above.
400 / success: false Bad or missing field (Ashby often answers 200 with success: false and errors) Read errors and fix the ids or fields named there.
429 Rate limit Wait and retry with backoff.

Store the key as a VX Agents basic-auth credential (username = API key, password empty).

Usage guide

Setup

  • Credential: an Ashby API key (Admin > Integrations > API Keys) stored as a basic-auth credential: username = the key, password empty. Grant candidatesRead, jobsRead, interviewsRead and hiringProcessMetadataRead; add candidatesWrite only if notes, tags, new candidates or stage moves are wanted.
  • Worth pinning: the jobId of the role you are hiring for (from listJobs with status: ["Open"]).

Review a candidate and move them forward

Every call is a POST with a JSON body, even reads.

  1. searchCandidates with email and/or name, then getCandidate with id for profile, tags and application ids.
  2. getApplication with applicationId for the job, current stage and status. listApplications with jobId and status (Active, Hired, Archived, Lead) lists a whole pipeline.
  3. Context: listApplicationHistory (stages and dates), listApplicationFeedback (scorecards), listCandidateNotes, and listInterviewSchedules with applicationId for booked interviews.
  4. getJob for the job's interview plan id, then listInterviewStages with interviewPlanId to get the stage ids in order.
  5. Write back, after the user confirms: createCandidateNote (candidateId, note as text or {type: "text/html", value}), addCandidateTag (tagId from listCandidateTags), or changeApplicationStage (applicationId, interviewStageId).
  6. To reject, move to the plan's stage of type Archived with an archiveReasonId from listArchiveReasons. Adding archiveEmail sends the candidate an email, so only do it when the user explicitly asks.

New candidates: createCandidate needs name; add email, phoneNumber, linkedInUrl and a sourceId from listSources. Always confirm before creating candidates or changing stages.

Good to know

  • Ashby can answer HTTP 200 with success: false and an errors list: check success on every response. Data is in results.
  • Lists page with cursor (from nextCursor while moreDataAvailable is true) and limit (page size). syncToken returns only changes since the last full sync.
  • Timestamps are ISO 8601 UTC. Ids are UUIDs.
  • Confidential jobs and private fields stay hidden unless the key has those extra permissions.
  • Source: Ashby API reference (https://developers.ashbyhq.com/reference/candidatelist), checked 2026-10-22.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Ashby Candidates & Applications” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • BambooHR Time Off & Employee Directory — Who is out today, and who asked for leave next week? Reads BambooHR's Who's Out calendar and time off requests, looks p…
  • Square Staff Shifts & Timecards — Who is working Saturday, and did everyone clock out last night? For salons, cafes and shops on Square: draft and publis…
  • Personio HR — Lets an agent look up employees in Personio, check absence types and existing time-off, book new absences and review at…
  • Clockify Time Off & Holidays — Who is off next week, and how many vacation days does Ana have left? Read Clockify time off policies and balances, list…
  • BambooHR Hiring & Applicant Tracking — Who applied for the open roles this week, and who is still waiting on a reply? Work the BambooHR ATS pipeline: list job…