> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Ashby
> Import your live Ashby job postings and exchange assessment results with Gradient
# Ashby
Ashby is a Gradient [ATS integration](/integrations) partner. Connecting Ashby gives
Gradient two capabilities:
* **Job import**: Create Gradient [roles](/concepts/roles) from your live Ashby job
postings, and pull candidates in.
* **Assessment partner**: Ashby starts Gradient assessments from a candidate's
profile and receives the scores back.
To set up the integration, you paste an Ashby key into Gradient, then
Gradient gives you a key to paste back into Ashby.
## What you'll need
* An Ashby **admin** account (to create the API key and configure the app).
* A Gradient **owner or admin** account (to connect the key and mint a partner key).
* About 10 minutes.
***
## Part 1: Create an Ashby API key
You create the Ashby API key from [the **Gradient tile** in Ashby's Integrations
Marketplace](https://app.ashbyhq.com/admin/integrations/marketplace/Gradient).
1. In Ashby, open **Admin**.
2. Open the **Integrations Marketplace** and find the **Gradient** tile. Tick
**Show unlaunched integrations** if you don't see it yet. Enable the
integration on the tile to create an Ashby API key.
3. Copy the key from the tile now. **Ashby only shows it once.**
The key is shown once. If you lose it, disable and re-enable the integration on
the tile to create a new one, then reconnect in Gradient.
***
## Part 2: Connect Ashby in Gradient and get your Gradient key
Do both of these in one visit to Gradient: connect your Ashby key, then generate
the Gradient key you'll paste back into Ashby in Part 3.
1. In Gradient, go to **Settings, Integrations**.
2. On the **Ashby** card, click **Connect**.
3. Paste your Ashby API key and click **Connect**. Gradient checks the key with a
live call before storing it (encrypted at rest).
4. Once connected, the **Ashby** card shows **Manage**. Open it: **Job import**
should read **Working**.
5. Under **Assessment partner**, click **Generate partner key** and copy the key.
It is shown **once**. (Use **Rotate partner key** later to replace it; the old
one stops working immediately.)
***
## Part 3: Configure the Gradient app in Ashby
Now paste the Gradient partner key back into Ashby to finish connecting the two tools.
1. In Ashby, open the **Gradient** tile in the **Integrations Marketplace**.
2. Fill in its configuration:
* **Partner API key** (the Gradient-named key field): paste the **Gradient
partner key** from Part 2.
* **Ashby API key**: the Ashby key from Part 1 (the one Gradient uses to write
scores back).
3. Click **Enable Gradient**.
All required fields must be filled before enabling. An empty partner key leaves
the app **not fully configured**, and **Enable** will fail with a generic Ashby
error.
Ashby can now start Gradient assessments from a candidate's profile, and
completed scores post back automatically.
***
## Part 4: Import your live job postings
With Ashby connected, you can seed a role from a real posting.
1. Go to **Roles**.
2. Click **Import from ATS**.
3. Search for a live posting and select it. Gradient pulls the title and job
description into the role, ready to edit.
***
## Part 5: Add a Gradient assessment to a job in Ashby
With the app enabled, you attach a Gradient assessment to the point in your Ashby
hiring process where you want candidates to take it. In Ashby, an assessment is an
activity on an interview stage. See Ashby's own guide,
[Setting up assessment integrations](https://docs.ashbyhq.com/setting-up-assessment-integrations),
for the authoritative version.
In Ashby, open the job and choose **Interview Plan** from the left sidebar.
On the stage where you want the assessment, click **Add Activity**, then pick
**Gradient** from the **Integrations** section.
Select the Gradient assessment from the dropdown — the list comes from your
connected Gradient workspace — and choose who should be notified to review the
results once a candidate finishes.
On a candidate at that stage, the Gradient activity shows a **Start
Assessment** button. Once the candidate finishes, the score and summary post
back into the same activity.
### Add an assessment to a single candidate
You can also use Ashby to send a Gradient assessment to an individual candidate, outside of an interview plan.
To send it to one candidate as a one-off, open their profile in Ashby, click **New Activity**, and
choose **Assessment**. Pick the Gradient assessment the same way. The score and
summary post back to that activity when they finish.
Gradient appears in the **Integrations** activity list (and the **Assessment**
option above) only after the app is enabled (Part 3). If you do not see it,
revisit the Gradient tile configuration.
***
## Troubleshooting
The app is not fully configured. Confirm the **partner key** field is filled
on the Ashby tile (Part 3). The error ID in Ashby's message is Ashby-internal,
so share it with Ashby support if the field is correct and it still fails.
The connected Ashby key lacks **job/application read** access. Create a key
with those scopes and reconnect in Gradient.
The write-back uses the Ashby key stored in Gradient, which needs **candidate
write** access. Reconnect with a key that has it. Verify the connection with
**Check connection** in Settings, Integrations.