Skip to main content

​
About Ashby

Ashby is an all-in-one recruiting platform covering applicant tracking, interview scheduling, sourcing, and hiring analytics. The Serval integration stores an Ashby Admin API key and uses it to call the Ashby API on behalf of your workflows - listing candidates, creating jobs, managing offers, and everything in between. Your key is only ever sent to Ashby’s own API. Authentication: API key. You paste an Ashby Admin API key once; Serval stores it and attaches the correct authentication to every Ashby request automatically. Data sync: on demand. There are no background syncs and no webhook ingestion on Serval’s side - Serval calls Ashby only when a workflow runs.

​
What the Ashby integration enables

Anything defined in the Ashby API can be accessed through Serval.

​
Get your credentials

You need an Ashby Admin API key whose permissions cover the endpoints your workflows will call. The full endpoint catalog is in the Ashby API reference.
1

Log in to Ashby

Sign in at app.ashbyhq.com. You need admin permissions - if you don’t see the API Keys option in the next step, contact your Ashby administrator.
2

Open the API Keys page

Navigate to Admin → Integrations → API Keys.
3

Create a new key

Click + New to open the API key setup wizard and enter a descriptive name (for example, “Serval Integration”). Optionally select an Integration Partner.
4

Grant endpoint permissions

New Ashby API keys start with no permissions at all. A key with missing permissions saves fine in Serval but fails later when a workflow runs.
Use the checkboxes to grant read and/or write access per module. Hover the i icon next to each module to see exactly which endpoints it covers, and optionally enable access to confidential jobs.
Grant what your workflows will actually use - for example, Candidates read for List Candidates and Candidates write for Create Candidate.
5

Save and copy the key

Click Save and Continue, then copy the API key and store it securely. Anyone with the key can act within its granted permissions.

​
Connect in Serval

1

Open the Ashby integration

In Serval, open the Ashby integration and start a new connection. The connect form has two fields.
2

Instance Name

A display name that identifies this Ashby connection inside Serval (for example, “Ashby”). The same field appears again, pre-filled, on the connection’s settings page, so the name can be changed later if needed.
3

API Key

Paste the Ashby Admin API key exactly as Ashby shows it - Serval builds the authentication header for you, so don’t encode the key or add any prefix. The field is a password input; after saving, it displays as bullets with only the last 4 characters visible.
4

Save

Submit the form. Neither field is validated, and Serval does not test the key against Ashby at this point - a typo won’t surface until a workflow runs (see “Verifying the connection” below). If the save itself fails, you may see “Failed to connect service”, “Failed to install integration”, or “Failed to save configuration. Please try again.” depending on where you connected from - these mean the form didn’t save, not that the key is bad.

​
Verifying the connection

This integration ships no automatic health checks, and connecting does not test your key against Ashby. To confirm everything works end to end, install and run the List Candidates workflow right after connecting:
  • If it returns your candidates, the key and its Candidates read permission are working.
  • If it fails with an authentication or permission error, re-enter the API key in full (raw key, no prefix) and check the key’s module permissions in Ashby.
An under-permissioned key can look healthy and still fail on specific actions - a key that lists candidates fine will still fail to create one if the Candidates module only has read access. When one workflow works and another doesn’t, check that module’s read/write grants in the Ashby key wizard first.

​
Gotchas and troubleshooting

Saving the connect form stores the credentials without calling Ashby, and there are no automatic health checks. An invalid or under-permissioned key surfaces as an error the first time a workflow calls the Ashby API, not at connect time. Run a quick workflow (such as List Candidates) immediately after connecting to verify.
Ashby keys grant nothing by default. In the key wizard, enable read and/or write per module to cover every endpoint your workflows call. A missing module permission shows up as an API error at workflow run time.
Serval builds the authentication for you. Do not encode the key or add any prefix - paste it exactly as Ashby displays it. A modified key fails on the first workflow run.
On the integration settings page, the saved key shows as an obfuscated value with a small pencil (edit) icon next to it. Click the pencil, paste the complete new key into the input (placeholder: “Enter new value”), and click Update. In the reconnect dialog, the same field shows a Replace button instead - click it and paste the full new key there. Either way, always paste the entire key: do not clear a pre-filled field and submit, and whenever you edit anything about the connection, re-enter the API key in full as part of the same save. If the connection misbehaves after an edit, re-enter the API key and save again. If the update itself fails, the settings page shows “Failed to update configuration”, and the reconnect dialog shows “Failed to update integration:” followed by error details.
The Instance Name field appears pre-filled on the connection’s settings page. To rename the connection, change it there - and, as with any edit, re-enter the API key in full as part of the same save.
Ashby’s API uses POST requests for everything - even reads. The operation name is part of the request address, not the method. Workflows that try to use GET will not match the Ashby schema.
Ashby list operations return results a page at a time, with a flag indicating more data is available and a cursor for the next page. Workflows should keep requesting with the returned cursor until no more data remains - the shipped List Candidates workflow accepts cursor and syncToken inputs for exactly this.
Need help? Contact support@serval.com for assistance with your Ashby integration.