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

# Ashby

> Read your hiring pipeline, move applications between stages, and note candidates.

Ashby connects with an API key created by an Ashby admin. It reads jobs, candidates, applications, interviews, and offers, and can write notes and stage changes back.

## What you can do

**Actions** - list jobs, search candidates, get a candidate, create a candidate, add a note to a candidate, list applications, get an application, list interview stages, move an application to a stage, list interview schedules, list offers, list users.

**Triggers** - none. Use it through the assistant in chat or as an action node in an automation.

## Get your credential

<Steps>
  <Step title="Open the Ashby admin">
    Sign in at [app.ashbyhq.com](https://app.ashbyhq.com/admin/api/keys) and open **Admin →
    Integrations → API Keys**. Creating a key requires Ashby admin access.
  </Step>

  <Step title="Create a key with the right permissions">
    Permissions are chosen per module when the key is created. Grant read access to **Jobs**,
    **Candidates**, **Interviews**, and **Offers** for the read actions, and write access to
    **Candidates** if agents should post notes or move applications between stages.
  </Step>
</Steps>

## Connect

<Steps>
  <Step title="Open Integrations">
    In arg.ai, go to **Settings → Integrations** and click **Connect** on **Ashby**.
  </Step>

  <Step title="Paste the key">Enter your API key in the API key field.</Step>

  <Step title="Save">
    arg.ai asks Ashby what the key is called and what it may do, and labels the connection with the
    answer. A key that isn't permitted to read its own permissions still connects - it just shows
    unlabelled. Nothing in Ashby is changed by the check.
  </Step>
</Steps>

## Use it

* **In chat:** *"Who is stuck in onsite for the Staff Engineer role?"*
* **In an automation:** add an **Ashby** action node to create a candidate whenever a referral form is submitted.

## How the pipeline fits together

A **job** is the role. A **candidate** is the person. An **application** joins the two and carries the interview stage the person is currently at, so a pipeline question is almost always a question about applications - list them filtered by `jobId` or `status`, and read `ashby_get_application` for one in full.

Moving someone forward takes a stage id, not a stage name. Read a job's `interviewPlanIds` from **list jobs**, pass one to **list interview stages**, then use that stage's id with **move an application to a stage**. Archiving is the same call to a stage of type `Archived`, and Ashby requires an archive reason id with it.

## Notes and permissions

A note posted as plain text renders any markup literally, so set the HTML option when the note carries any. Notifications to everyone subscribed to the candidate are off unless you ask for them.

An Ashby key is org-wide rather than per-person: what an agent can read or write follows the key's permissions, not the permissions of whoever asked. Cut a read-only key if agents should never change anything.