Ashby

Add a candidate to a project in Ashby. Projects are sourcing initiatives or recruiting campaigns used to organize and track candidate pipelines. Use this to associate candidates with specific sourcing efforts. Common use cases: - Adding sourced candidates to recruiting campaigns - Organizing candidates by sourcing channel or initiative - Tracking candidates in specific hiring projects Requires candidatesWrite permission. Returns the updated candidate object on success, or error details if the candidate or project is not found.

Add a tag to a candidate in Ashby. Use this to categorize and organize candidates with existing tags from the system. This action allows you to apply labels/tags to candidates for filtering, searching, and organizational purposes. Tags must already exist in the system - use LIST_CANDIDATE_TAGS to view available tags or CREATE_CANDIDATE_TAG to create new ones. The response includes the full updated candidate object when successful, showing the newly added tag in the candidate's tags array. If a candidate already has the tag, the operation will still succeed idempotently.

Add an Ashby user to a hiring team at the application, job, or opening level. Use this when you need to assign a team member to participate in the hiring process with a specific role. Requires the organizationWrite permission.

Add a user to an interviewer pool. Use this to assign interviewers to interview pools for scheduling and coordination. Requires the hiringProcessMetadataWrite permission.

Adds a job to an opening (job requisition) in Ashby ATS. An opening represents a position to be filled, while a job defines the role details. This action associates an existing job with an existing opening, allowing multiple jobs to be linked to a single opening. Use this when you need to add job definitions to an opening or when creating multi-role requisitions. Requires the jobsWrite permission. On success, returns the updated opening with the job added to its jobIds array. On failure, returns error details with specific error codes.

Tool to add a location to an opening (job requisition). Use when you need to associate a location with an existing opening. Requires the jobsWrite permission.

Anonymize a candidate by removing personally identifiable information. Use this when you need to permanently anonymize a candidate's data. This action cannot be reversed and requires all of the candidate's applications to be in the archived or hired state.

Approve an offer or a specific approval step within an offer's approval process. This action supports two modes: - Complete offer approval: Provide only offerId to approve the entire offer - Step-specific approval: Provide offerId, approvalStepId, and userId to approve a specific step When approving a specific step, both approvalStepId and userId are required together. Requires the 'offersWrite' permission.

Archive a department by its unique identifier. Archiving a department marks it as inactive while preserving all its data and historical records. Archived departments are excluded from active department lists by default but can be restored later using the restore department action. This action is idempotent - archiving an already archived department will succeed and return the same result. Required permission: organizationWrite

Archive an interviewer pool in Ashby. This marks the pool as archived, making it unavailable for new interview assignments while preserving historical data. Use this when an interviewer pool is no longer needed (e.g., for deprecated roles or outdated interview formats). The operation is idempotent - archiving an already archived pool will succeed without errors. Requires the hiringProcessMetadataWrite permission. To restore an archived pool, use the ASHBY_RESTORE_INTERVIEWER_POOL action.

Archives a location or location hierarchy in Ashby. When archived, the location is marked as inactive (isArchived=true) and typically becomes unavailable for new job postings or assignments. The operation is idempotent - archiving an already archived location succeeds without error. Requires the organizationWrite permission. Common use cases: - Decommissioning office locations that are no longer in use - Removing obsolete location entries from active use - Managing location lifecycle when restructuring office locations Note: Use restore_location to unarchive a location if needed.

Change the source attribution of an application. Use this to update which source and user should be credited for bringing in the candidate.

Move an application to a different interview stage in the hiring pipeline. Use this to: - Advance candidates to the next interview stage (e.g., from "Application Review" to "First Round") - Move candidates to any stage within their job's interview plan (forward or backward) - Archive applications by moving to an Archived stage (requires archiveReasonId) - Move to Offer or Hired stages when progressing candidates Important: The interview stage must belong to the same interview plan as the application's job. Use LIST_INTERVIEW_STAGES with the application's job interview plan ID to get valid stage options.

Create a new job application by associating a candidate with a job opening in Ashby ATS. Use this action to: - Add a candidate to a job's hiring pipeline and interview process - Track the source of the application (referral, job board, etc.) - Credit a user (recruiter/referrer) for bringing in the candidate - Place the candidate directly into a specific interview stage (optional) The created application will automatically be assigned to the job's hiring team and start tracking the candidate's progress through the interview stages. Required: candidateId and jobId must reference existing entities in Ashby.

Create a new candidate in the system. Use this to add candidates with their contact information and social profiles before applying them to jobs.

Create a note on a candidate profile. Use this to add comments, observations, or feedback about a candidate during the recruitment process.

Create a new candidate tag in Ashby for categorizing and organizing candidates. Tags are labels that help you filter, search, and group candidates for better organization and workflow management. Use this action to create custom tags based on skills, experience levels, departments, or any other criteria relevant to your hiring process. Returns the newly created tag with its unique ID, title, and archived status. Tags are created in an active (non-archived) state by default.

Create a new custom field in Ashby. Custom fields allow you to track additional structured data on Ashby objects like candidates, applications, and jobs. This action creates the field definition that can then be populated with values using the set custom field value actions. Supported field types: - String: Free text input - Number: Numeric values - Boolean: True/false values - Date: Date values (optionally date-only without time) - ValueSelect: Single selection from predefined options - MultiValueSelect: Multiple selections from predefined options - Employee: Reference to an Ashby employee (limited object type support) Note: ValueSelect and MultiValueSelect field types require the selectableValues parameter. Requires the hiringProcessMetadataWrite permission.

Create a new department. Use this to add organizational departments or teams for structuring jobs and hierarchy.

Create a new interviewer pool. Use this to organize interviewers into groups by expertise or interview type. Requires the hiringProcessMetadataWrite permission.

Create a new job opening in Ashby ATS. Use this action to: - Add a new role to your organization with a title, department, location, and brand - Set up the job structure before publishing or opening it to candidates - Optionally assign a default interview plan to define the hiring process Important notes: - Newly created jobs start in 'Draft' status and cannot accept applications yet - To open the job for applications, you must set a defaultInterviewPlanId either during creation or update it later - Use LIST_DEPARTMENTS, LIST_LOCATIONS, LIST_BRAND, and LIST_INTERVIEW_PLANS actions to get valid IDs - The job creator is automatically set as the author

Create a new location or location hierarchy. Use this to add office locations, remote work settings, or nested location structures for organizational management.

Create a new offer for a candidate in Ashby ATS. Use this to generate formal job offers with all required field values after starting an offer process and obtaining the form definition. Prerequisites: Must first call offerProcess.start to get offerProcessId, then offer.start to get offerFormId and field definitions. Date fields must use YYYY-MM-DD format (not ISO timestamp).

Create a new opening (job requisition) in Ashby ATS. An opening represents a job requisition - a request to hire for a specific position. All parameters are optional, but typically you'll want to provide at least a title, job IDs, and location IDs for a meaningful opening. Use this action to: - Create a new job opening with specific requirements - Associate openings with existing jobs, locations, and teams - Set hiring targets, employment type, and opening state - Track backfill positions vs new roles Required permission: openingsWrite Note: To get valid IDs for teamId, locationIds, and jobIds, use the corresponding List Departments, List Locations, and List Jobs actions.

Create a referral in Ashby ATS by submitting a referral form with candidate information. Use this action to formally submit employee referrals for job openings, which creates both a candidate record (if new) and an application linked to the specified job.

Generate a survey request and receive a survey URL to send to a candidate. Use this when you need to collect feedback or information from candidates via a survey. Requires candidatesWrite permission. Note that calling this endpoint does not automatically email the survey to the candidate.

Create a new survey submission for a candidate's application. Use this to submit candidate survey responses programmatically, such as candidate experience ratings or feedback forms. Requires the candidatesWrite permission.

Retrieve information about the current API key, including associated organization, user details, and permissions. Use this to verify API key validity and check what access level the key has. Useful as a prerequisite check before write operations (e.g., ASHBY_UPDATE_CANDIDATE) or list operations (e.g., ASHBY_LIST_APPLICATIONS) to confirm the key has required scopes.

Retrieve detailed information about a specific application by its ID. Returns complete details including candidate info, interview stages, and hiring team nested under data.results. To find a recruiting coordinator, match hiringTeam entries where role == "Recruiting Coordinator" (exact string). Optional fields such as primaryEmailAddress may be null; handle accordingly.

Retrieve detailed information about a specific candidate by their ID. This action returns comprehensive candidate data including: - Basic information (name, position, company, school) - Contact details (email addresses, phone numbers) - Social profiles (LinkedIn, etc.) - Associated applications and tags - Custom field values - Source and credited user information - Location and timezone - Profile URL Use this when you need complete details about a specific candidate. To find candidate IDs, use the list_candidates or search_candidates actions first.

Retrieve detailed information about a specific custom field by its ID. Use this to get custom field details including title, object type, field type, and selectable values. Requires the hiringProcessMetadataRead permission.

Retrieve detailed information about a specific department by its ID. Returns comprehensive department details including: - Department name (internal and external) - Parent department relationship (parentId for hierarchical structure) - Archive status (isArchived) - Creation and last update timestamps Use this action when you need information about a specific department (e.g., to verify a department exists, check its archive status, or understand organizational hierarchy). For listing all departments or finding department IDs, use the List Departments action instead. Requires 'organizationRead' permission.

Retrieve detailed information about a specific feedback form definition by its ID. Use this action to: - Get the complete structure of a feedback form including all sections and fields - View field types (ValueSelect, MultiValueSelect, Boolean, RichText) and their configurations - Check if a form is the default form or a custom scorecard - See which interview the form is linked to (if any) - Access selectable values and field metadata for form rendering To find available feedback form IDs, use the List Feedback Form Definitions action first. Requires the hiringProcessMetadataRead permission.

Retrieve the URL of a file associated with a candidate. Use this to get a pre-signed S3 URL for accessing candidate files like resumes. Requires the candidatesRead permission.

Retrieve detailed information about a specific interviewer pool by its ID. Returns comprehensive pool information including: - Basic details (ID, title, archived status) - Qualified members who can conduct interviews - Trainees currently in training - Training path configuration with stages and requirements Use this to view interviewer pool composition, training programs, and member status for scheduling interviews or managing interviewer assignments.

Get interviewer settings for a specific user by their ID. Use this to retrieve daily and weekly interview limits configured for the user. Requires the organizationRead permission.

Retrieve detailed information about a specific interview type by its ID. Use this to get interview details including title, instructions, and feedback form configuration.

Tool to fetch interview stage details by ID. Use when you need specific information about an interview stage including its title, type, order, and parent interview plan. Requires the interviewsRead permission.

Retrieve detailed information about a specific job by its ID. Use this to get complete details about a job including title, status, hiring team, interview plans, and more. Job offer payloads omit full job details; combine with ASHBY_LIST_APPLICATIONS and ASHBY_GET_APPLICATION_INFO for complete reporting data.

Retrieve the interview plan information for a specific job. Use this to get details about the interview stages and process configured for a job.

Retrieve detailed information about a specific job posting by its ID. Use this to get complete job posting details including full description, application form fields, compensation, and publish settings.

Retrieve detailed information about a specific location by its ID. Use this to get complete location details including address, remote status, and workplace type.

Retrieve detailed information about a specific offer by its ID. This action returns comprehensive offer data including application ID, status, version, timestamps, candidate ID, job ID, start date, and custom fields. Use this when you need complete details about a specific offer. To find offer IDs, use the list_offers action first. Requires the 'offersRead' permission.

Retrieve detailed information about a specific opening (job requisition) by its ID. An opening represents a headcount position that needs to be filled. Each opening belongs to a job and tracks hiring progress including state (Open/Closed), hiring team members, employment type, and target dates. Use this action to: - Get complete details about a specific opening including its current state - View the hiring team assigned to the opening - Check employment type, target hire date, and target start date - Access custom fields associated with the opening Returns opening details on success, or error information if the opening ID is invalid.

Fetches the default referral form or creates a default referral form if none exists. Requires the hiringProcessMetadataRead permission.

Retrieve detailed information about a specific survey form definition by its ID. This action returns comprehensive details about a survey form including: - Survey title and type (e.g., Diversity, EEOC, QualityOfHire) - Form definition with sections and fields - Field types (ValueSelect, MultiValueSelect, RichText, LinearRating, etc.) - Selectable values for choice fields - Required field indicators - Archive status Use the LIST_SURVEY_FORM_DEFINITIONS action first to discover available survey form IDs. Common survey types include candidate experience surveys, hiring manager assessments, quality of hire evaluations, and EEOC compliance forms. Requires the hiringProcessMetadataRead permission.

Retrieve detailed information about a specific user by their ID. Use this to get user details including name, email, role, and permissions.

Retrieve AI-generated criteria evaluations for an application. Use this to get the AI assessment of how well a candidate meets specific job requirements, including evaluation outcomes and reasoning.

Retrieve all feedback submissions for an application. Use this to view interviewer feedback, evaluations, and notes collected throughout the hiring process.

Retrieve all available hiring team roles for applications in the organization. These roles can be assigned to hiring team members at the application level (e.g., Recruiter, Hiring Manager, Recruiting Coordinator, Sourcer). Use this endpoint to get the complete list of role IDs and titles that are available for assignment. Requires candidatesRead permission. Note: This differs from the general hiring team roles list - this specifically returns roles used at the application level in the hiring workflow.

Retrieve the complete history of stage transitions for an application. Use this to get detailed information about when and how a candidate moved through different interview stages.

Retrieve a list of applications with optional pagination and sync-token filtering for incremental updates. No server-side recruiter filter exists; attribute applications to team members client-side.

Retrieve a list of approvals (offer approvals, job approvals, etc.). Use this to track approval workflows and pending approvals.

Retrieve a list of all archive reasons. Use this to see available reasons for archiving candidates or applications, such as rejection categories.

Retrieve a list of all brands for the organization. Use this to get available brands for job postings and employer branding. Requires organizationRead permission.

Retrieve all client info records for a specific candidate with pagination support. Client info records contain additional client-specific information associated with candidates in your Ashby account. This endpoint supports pagination and incremental synchronization for efficient data retrieval. Use the cursor and limit parameters to paginate through large result sets. For incremental syncing, use the syncToken to fetch only changes since your last sync. Requires candidatesRead permission.

Retrieve all notes for a specific candidate in Ashby. Use this action to view comments, observations, and internal notes added by recruiters and hiring team members during the hiring process. Common use cases: - Review feedback and observations from interviewers - Check historical communication and decisions about a candidate - Audit the hiring process for a specific candidate Prerequisites: - You need a valid candidateId. Get this from list_candidates or search_candidates. - Requires 'candidatesRead' permission in Ashby. Returns an empty list if the candidate has no notes.

Retrieve all projects associated with a candidate. Use this to see which sourcing projects or recruiting initiatives a candidate is part of.

Retrieve a list of candidates. Use this to fetch all candidates with optional pagination and filtering by sync token for incremental updates.

Retrieve a list of all candidate tags in your Ashby account. Tags are labels used to categorize and organize candidates for filtering and search purposes. Use this action to: - Get all available tags for tagging candidates - Implement incremental sync using the syncToken parameter - Paginate through large sets of tags using cursor Returns tag id, title, and archived status for each tag.