> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Search candidates and move applications with Ashby agents

> Connect Guild agents to Ashby to search candidates, read and advance applications, manage jobs, schedule interviews, and work with offers and pipeline data.

<div className="guild-lockup">
  <span className="guild-eyebrow">Integrations · Ashby</span>
</div>

A Guild agent can search candidates, move applications through hiring stages, schedule interviews, and manage offers in Ashby. Guild stores the API key server-side and injects it through the credential proxy, so the key never appears in agent code or prompts. Credential policies let you restrict which Ashby operations each agent can call.

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use Ashby.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect Ashby and scope your first agent.
  </Card>
</CardGroup>

## What the Ashby integration exposes

The tools cover candidates, applications, jobs, openings, interview plans and schedules, offers, approvals, feedback forms, surveys, custom fields, departments, locations, and users. Read operations fetch lists and individual records; write operations create, update, transfer, and archive them. Tools for hiring team membership, interviewer pools, and source tracking are also included.

## How it works

<Steps>
  <Step title="Create an Ashby API key">
    In Ashby, go to Admin > API Keys and create a key with the permissions your agent needs.
  </Step>

  <Step title="Encode the key">
    Run the base64 command shown on the integration page, appending a colon to the key before encoding. The trailing colon marks the empty password that Ashby Basic auth requires.
  </Step>

  <Step title="Connect the credential in Guild">
    In Guild, go to Access & setup > Credentials, click Connect, select ashby, and paste the encoded output into API Key. See [Credentials](/platform/credentials) for workspace, member, and agent-scoped options.
  </Step>
</Steps>

## Why Ashby access needs governing

Ashby holds sensitive hiring data: candidate profiles, compensation in offers, fraud check results, and feedback scorecards. An agent with an unconstrained credential can read or write any of that data. [Credential policies](/platform/credential-policies) let you write ALLOW and DENY rules that Guild's proxy enforces before any request reaches Ashby, limiting an agent to the specific operations it needs, such as read-only candidate search or stage changes only.

Guild stores the API key server-side and injects it after the policy check passes. Agent code, prompts, and container environments never see the key. You can scope a credential to one workspace, one member, or a single agent using the options described in [Credentials](/platform/credentials), and every call is logged so you can audit what each agent did.

## About the Ashby integration

The Ashby integration gives agents the Ashby API: candidates, applications, jobs and openings, interview plans and schedules, offers, feedback, and custom fields. The integration is `guildlabs~ashby`.

## Authentication

* **Type:** API key, sent as HTTP Basic authentication

Ashby authenticates with Basic auth, using the API key as the username and an empty password. Guild sends the value you enter as `Authorization: Basic <value>`, so enter the key followed by a colon, base64-encoded:

```bash theme={null}
echo -n "<Ashby API key>:" | base64
```

Keep the trailing colon: it marks the empty password.

### Setup

<Steps>
  <Step title="Create an API key">In Ashby, go to **Admin > API Keys** and create a key with the permissions your agent needs.</Step>
  <Step title="Encode it">Run the command above with the key.</Step>
  <Step title="Connect Ashby">In Guild, go to **Access & setup > Credentials**, click **Connect**, select **ashby**, and paste the output into **API Key**.</Step>
</Steps>

See [Credentials](/platform/credentials) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { AshbyTools } from "@guildai-services/guildlabs~ashby"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that answers questions about candidates in Ashby",
  tools: { ...AshbyTools },
})
```

### Selecting specific tools

Tools are named with the `ashby_` prefix and a `_v2` suffix. The integration has 160 tools, so use `pick()` to include only what your agent needs.

```typescript theme={null}
import { AshbyTools } from "@guildai-services/guildlabs~ashby"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that summarizes a candidate's applications and interviews",
  tools: {
    ...pick(AshbyTools, [
      "ashby_candidate_search_v2",
      "ashby_candidate_info_v2",
      "ashby_application_list_v2",
      "ashby_interview_schedule_list_v2",
    ]),
  },
})
```

## Tools

Tools in the latest published version of `guildlabs~ashby`:

<Accordion title="All 160 tools">
  | Tool | What it does |
  | - | - |
  | `ashby_api_key_info_v2` | Retrieve information about the API key being used to make the request. |
  | `ashby_applicationaddhiringteammember_v2` | Adds an Ashby user to the hiring team at the application level. |
  | `ashby_application_change_source_v2` | Change the source of an application. |
  | `ashby_application_change_stage_v2` | Change the stage of an application |
  | `ashby_application_create_v2` | Consider a candidate for a job (eg when sourcing a candidate for a job posting). |
  | `ashby_application_feedback_list_v2` | List all interview scorecards and feedback submissions associated with an application. |
  | `ashby_applicationfeedbackrequestcreate_v2` | Request feedback on an application without scheduling an interview. |
  | `ashby_applicationfeedbacksubmit_v2` | Application feedback forms support a variety of field types. |
  | `ashby_applicationformsubmit_v2` | Submit an application for a job posting. |
  | `ashby_application_hiring_team_role_list_v2` | Gets all available hiring team roles for applications in the organization. |
  | `ashby_application_info_v2` | Fetch application details by application id or by submitted form instance id (which is return by the `applicationForm.submit` endpoint). |
  | `ashby_application_list_criteria_evaluations_v2` | Fetch a paginated list of AI criteria evaluations for an application. |
  | `ashby_application_list_history_v2` | Fetch a paginated list of application history items for an application. |
  | `ashby_application_list_v2` | Gets all applications in the organization. |
  | `ashby_applicationremovehiringteammember_v2` | Removes an Ashby user to the hiring team at the application level. |
  | `ashby_application_transfer_v2` | Transfer an application to a different job. |
  | `ashby_application_update_history_v2` | Update the history of an application. |
  | `ashby_application_update_v2` | Update an application |
  | `ashby_approval_definition_update_v2` | Create or update an approval definition for a specific entity that requires approval. |
  | `ashby_approval_list_v2` | Gets all approvals in the organization. |
  | `ashby_archivereasonlist_v2` | Lists archive reasons |
  | `ashby_assessment_add_completed_to_candidate_v2` | Add a completed assessment to a candidate |
  | `ashby_assessment_update_v2` | Update Ashby about the status of a started assessment. |
  | `ashby_brand_list_v2` | Lists all brands for the organization. |
  | `ashby_candidate_add_email_message_v2` | Adds an email message to a candidate's profile. |
  | `ashby_candidateaddproject_v2` | Adds the candidate to a project. |
  | `ashby_candidate_add_tag_v2` | Adds a tag to a candidate |
  | `ashby_candidate_anonymize_v2` | Anonymizes a candidate. |
  | `ashby_candidate_create_note_v2` | Creates a note on a candidate. |
  | `ashby_candidate_create_v2` | Creates a new candidate |
  | `ashby_candidate_info_v2` | Gets a single candidate by id. |
  | `ashby_candidate_list_client_info_v2` | Lists all client info records for a candidate. |
  | `ashby_candidate_list_fraud_checks_v2` | Fetches a paginated list of fraud checks for a candidate, including the fraud signals detected in each check. |
  | `ashby_candidate_list_notes_v2` | Lists all notes on a candidate. |
  | `ashby_candidate_list_projects_v2` | Lists all projects on a candidate. |
  | `ashby_candidate_list_v2` | Lists all candidates in an organization. |
  | `ashby_candidateremoveproject_v2` | Removes the candidate from a project. |
  | `ashby_candidate_remove_tag_v2` | Removes a tag from a candidate. |
  | `ashby_candidate_search_v2` | Search for candidates by email and / or name. |
  | `ashby_candidate_set_fraud_status_v2` | This endpoint allows marking candidates as fraudulent, not fraudulent, or unsure after reviewing their fraud signals via `candidate.listFraudChecks`. |
  | `ashby_candidate_tag_archive_v2` | Archives a candidate tag. |
  | `ashby_candidatetagcreate_v2` | Creates a candidate tag. |
  | `ashby_candidate_tag_list_v2` | Lists all candidate tags. |
  | `ashby_candidate_update_v2` | Updates an existing candidate |
  | `ashby_candidate_upload_file_v2` | Uploads a file to attach to the candidate's profile. |
  | `ashby_candidate_upload_resume_v2` | Uploads a candidate's resume, parses it, and updates their information. |
  | `ashby_close_reason_list_v2` | Lists all close reasons for jobs or openings. |
  | `ashby_communication_template_list_v2` | List all enabled communication templates. |
  | `ashby_custom_field_create_v2` | Create a new custom field |
  | `ashby_custom_field_info_v2` | Get information about a custom field |
  | `ashby_custom_field_list_v2` | Lists all custom fields. |
  | `ashby_custom_field_set_values_v2` | Set the values of multiple custom fields for a given object in a single call. |
  | `ashby_custom_field_set_value_v2` | Set the value of a custom field for a given object. |
  | `ashby_custom_field_update_selectable_values_v2` | Update the selectable values for a custom field |
  | `ashby_departmentarchive_v2` | Archives a department |
  | `ashby_departmentcreate_v2` | Creates a department |
  | `ashby_department_info_v2` | Fetch department details by id |
  | `ashby_department_list_v2` | Lists all departments |
  | `ashby_departmentmove_v2` | Moves a department to another parent |
  | `ashby_departmentrestore_v2` | Restores a department |
  | `ashby_departmentupdate_v2` | Updates a department |
  | `ashby_feedback_form_definition_info_v2` | Returns a single feedback form by id |
  | `ashby_feedback_form_definition_list_v2` | Lists all feedback forms. |
  | `ashby_file_create_file_upload_handle_v2` | Creates a presigned upload URL that allows uploading a file directly to storage, bypassing the need to send file bytes through the API. |
  | `ashby_file_info_v2` | Retrieve the url of a file associated with a candidate |
  | `ashby_hiringteamaddmember_v2` | Adds an Ashby user to the hiring team at the application or job-level. |
  | `ashby_hiringteamremovemember_v2` | Removes an Ashby user from the hiring team at the application or job-level. |
  | `ashby_hiringteamrolelist_v2` | Lists the possible hiring team roles in an organization |
  | `ashby_interview_briefing_info_v2` | Fetch the briefing data for an interview event. |
  | `ashby_interviewer_pool_add_user_v2` | Add a user to an interviewer pool. |
  | `ashby_interviewer_pool_archive_v2` | Archives an interviewer pool. |
  | `ashby_interviewer_pool_create_v2` | Create an interviewer pool. |
  | `ashby_interviewer_pool_info_v2` | Get information about an interviewer pool. |
  | `ashby_interviewer_pool_list_v2` | List all interviewer pools. |
  | `ashby_interviewer_pool_remove_user_v2` | Remove a user from an interviewer pool. |
  | `ashby_interviewer_pool_restore_v2` | Restores an archived interviewer pool. |
  | `ashby_interviewer_pool_update_v2` | Update an interviewer pool. |
  | `ashby_interview_event_list_v2` | Lists interview events associated with an interview schedule |
  | `ashby_interview_info_v2` | Fetch interview details by id |
  | `ashby_interview_list_v2` | List all interviews. |
  | `ashby_interview_plan_list_v2` | List published interview plans. |
  | `ashby_interview_schedule_cancel_v2` | Cancel an interview schedule by id |
  | `ashby_interview_schedule_create_v2` | Create a scheduled interview in Ashby |
  | `ashby_interview_schedule_list_v2` | Gets all interview schedules in the organization. |
  | `ashby_interview_schedule_update_v2` | Update an interview schedule. |
  | `ashby_interview_stage_group_list_v2` | List all interview group stages for an interview plan in order. |
  | `ashby_interview_stage_info_v2` | Fetch interview stage details by id |
  | `ashby_interview_stage_list_v2` | List all interview stages for an interview plan in order. |
  | `ashby_job_board_list_v2` | List all enabled job boards. |
  | `ashby_job_create_v2` | Creates a new job |
  | `ashby_job_info_v2` | Returns details about a single job by id |
  | `ashby_job_interview_plan_info_v2` | Returns a job's interview plan, including activities and interviews that need to be scheduled at each stage |
  | `ashby_job_list_v2` | List all open, closed, and archived jobs. |
  | `ashby_job_posting_info_v2` | Retrieve an individual job posting |
  | `ashby_job_posting_list_v2` | Lists all published job postings |
  | `ashby_job_posting_update_v2` | Updates an existing job posting. |
  | `ashby_job_search_v2` | Searches for jobs by title |
  | `ashby_job_set_status_v2` | Sets the status on a job by id. |
  | `ashby_job_template_list_v2` | List all active and inactive job templates. |
  | `ashby_job_update_compensation_v2` | Updates an existing job's compensation tiers |
  | `ashby_job_update_v2` | Updates an existing job |
  | `ashby_locationarchive_v2` | Archives a location or location hierarchy. |
  | `ashby_locationcreate_v2` | Creates a location or location hierarchy. |
  | `ashby_location_info_v2` | Gets details for a single location by id. |
  | `ashby_locationlist_v2` | List all locations. |
  | `ashby_locationmove_v2` | Moves a location in location hierarchy. |
  | `ashby_locationrestore_v2` | Restores an archived location or location hierarchy. |
  | `ashby_locationupdateaddress_v2` | Update an address of a location or location hierarchy. |
  | `ashby_locationupdateexternalname_v2` | Update a location's external (candidate-facing) name. |
  | `ashby_locationupdate_name_v2` | Update location's name. |
  | `ashby_locationupdateworkplacetype_v2` | Update location's workplace type. |
  | `ashby_notetaker_transcript_info_v2` | Fetches metadata and a pre-signed download URL for an AI. |
  | `ashby_offer_approve_v2` | Approves an offer or a specific approval step within an offer's approval process. |
  | `ashby_offer_create_v2` | Creates a new Offer |
  | `ashby_offer_info_v2` | Returns details about a single offer by id |
  | `ashby_offer_list_v2` | Get a list of all offers with their latest version. |
  | `ashby_offer_process_start_v2` | Starts an offer process for a candidate. |
  | `ashby_offer_start_approval_process_v2` | Starts the approval process for an offer in a "WaitingOnApprovalStart" state. |
  | `ashby_offer_start_v2` | The offer.start endpoint creates and returns an offer version instance that can be filled out and submitted using the `offer.create` endpoint. |
  | `ashby_offer_update_v2` | Updates an existing Offer |
  | `ashby_openingaddjob_v2` | Adds a job to an opening. |
  | `ashby_openingaddlocation_v2` | Adds a location to an opening. |
  | `ashby_openingcreate_v2` | Creates an opening. |
  | `ashby_openinginfo_v2` | Retrieves an opening by its UUID. |
  | `ashby_openinglist_v2` | Lists openings. |
  | `ashby_openingremovejob_v2` | Removes a job from an opening. |
  | `ashby_openingremovelocation_v2` | Removes a location from an opening. |
  | `ashby_openingsearch_v2` | Searches for openings by identifier. |
  | `ashby_openingsetarchived_v2` | Sets the archived state of an opening. |
  | `ashby_openingsetopeningstate_v2` | Sets the state of an opening. |
  | `ashby_openingupdate_v2` | Updates an opening. |
  | `ashby_projectinfo_v2` | Retrieves an project by its UUID. |
  | `ashby_projectlist_v2` | Lists projects. |
  | `ashby_project_search_v2` | Search for projects by title. |
  | `ashby_referral_create_v2` | Creates a referral |
  | `ashby_referral_form_info_v2` | Fetches the default referral form or creates a default referral form if none exists. |
  | `ashby_report_generate_v2` | Generates a new report or polls the status of an existing report generation. |
  | `ashby_report_synchronous_v2` | Retrieves report data synchronously. |
  | `ashby_sourcelist_v2` | List all sources |
  | `ashby_sourcetrackinglinklist_v2` | List all source custom tracking links |
  | `ashby_survey_form_definition_info_v2` | Returns details about a single survey form definition by id |
  | `ashby_survey_form_definition_list_v2` | Lists all survey form definitions. |
  | `ashby_survey_request_create_v2` | This endpoint generates a survey request and returns a survey URL. |
  | `ashby_survey_request_list_v2` | Lists all survey requests. |
  | `ashby_survey_submission_create_v2` | Create a new survey submission. |
  | `ashby_survey_submission_list_v2` | Lists all survey submissions of a given `surveyType`. |
  | `ashby_user_create_interviewer_pause_v2` | Creates an interviewer pause for a user. |
  | `ashby_user_delete_interviewer_pause_v2` | Deletes an interviewer pause. |
  | `ashby_user_info_v2` | Get an Ashby user by id |
  | `ashby_user_interviewer_settings_v2` | Get interviewer settings for a user. |
  | `ashby_user_list_interviewer_pauses_v2` | Lists all active or scheduled interviewer pauses for a user. |
  | `ashby_user_list_v2` | Get a list of all Ashby users. |
  | `ashby_user_search_v2` | Search for an Ashby user by email address |
  | `ashby_user_set_custom_field_values_v2` | Set the values of multiple custom fields on an employee in a single call. |
  | `ashby_user_set_custom_field_value_v2` | Set the value of a custom field on an employee. |
  | `ashby_user_update_interviewer_settings_v2` | Update interviewer settings for a user. |
  | `ashby_webhookcreate_v2` | Creates a webhook setting. |
  | `ashby_webhookdelete_v2` | Deletes a webhook setting. |
  | `ashby_webhook_info_v2` | Retrieves information about a specific webhook setting by its ID |
  | `ashby_webhookupdate_v2` | Updates a webhook setting. |
</Accordion>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I limit an agent to reading candidates without letting it change applications?">
    Yes. [Credential policies](/platform/credential-policies) support ALLOW rules scoped to specific operations. You can allow operations like ashby\_candidate\_search\_v2 and ashby\_candidate\_info\_v2 while adding a DENY rule for ashby\_application\_change\_stage\_v2 and other write operations.
  </Accordion>

  <Accordion title="Does the integration receive Ashby webhook events?">
    Not yet. The catalog entry lists no webhook events for this integration, so agents cannot be triggered by Ashby events through Guild's event trigger system.
  </Accordion>

  <Accordion title="Can different agents use different Ashby accounts?">
    Yes. You can connect credentials at the workspace, member, or agent scope. Dedicating a credential to one installed agent means that agent uses its own Ashby API key while other agents use a separate account-level credential. See [Credentials](/platform/credentials) for how Guild resolves which credential to use.
  </Accordion>

  <Accordion title="Do I need to include all the tools or can I pick a subset?">
    You can pick a subset. The SDK's pick() function lets you spread only the named tools into your agent's tools object, which keeps the model's tool list focused on the task at hand.
  </Accordion>
</AccordionGroup>

## Put a governed agent on your Ashby hiring pipeline today

<CardGroup cols={2}>
  <Card title="Book a demo" icon="calendar" href="https://guild-ai.cal.com/gtm/meeting-with-guild.ai">
    See how teams govern agents that use Ashby.
  </Card>

  <Card title="Start free" icon="rocket" href="https://app.guild.ai">
    Connect Ashby and scope your first agent.
  </Card>
</CardGroup>

## Related

**Read:** Docs: [Credential policies](/platform/credential-policies) · [Credentials](/platform/credentials) · [Tools in agents](/sdk/tools)