Skip to main content

​
Ashby

Ashby is a Gradient ATS integration partner. Connecting Ashby gives Gradient two capabilities:
  • Job import: Create Gradient 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.
  1. In Ashby, open Admin.
    The Admin section of Ashby
  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.
    The Gradient tile in Ashby's Integrations Marketplace
  3. Copy the key from the tile now. Ashby only shows it once.
    The API key shown on the Gradient tile in Ashby
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).
    Gradient's Connect Ashby dialog with a field to paste the Ashby API key
  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.)
    Gradient's Manage Ashby dialog showing Job import Working and a Generate partner key button

​
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.
Roles page: Import from ATS button
  1. Search for a live posting and select it. Gradient pulls the title and job description into the role, ready to edit.
Import one job or many.

​
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, for the authoritative version.
1

Open the job's interview plan

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.
Adding an activity to the Skills Assessment stage of an Ashby interview plan
2

Choose the assessment and reviewers

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.
A Gradient Assessment activity attached to the Skills Assessment stage in Ashby
3

Start it from a candidate

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.
A candidate's Gradient Assessment activity in Ashby with a Start Assessment button

​
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.
The New Activity menu on an Ashby candidate profile, with Assessment selected
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.