Integrate Apployent with Ashby
An organization admin connects Ashby once. Each project then chooses how it uses that connection.
This article explains how to connect Apployent to Ashby and how each project uses that connection. Complete the Apployent steps in the Employer Portal. If you use a different ATS, start from Applicant Tracking Systems (ATS).
To start, an organization admin connects Ashby once under Org Admin → ATS Integration and enable / disable optional capabilities for the whole organization. That connection does not attach any project yet. Afterward, anyone who can edit a project (an owner or editor) chooses a sync mode for that project separately.
Organization setup
Someone on your team who is an organization admin in Apployent completes this step once. They also need permission in Ashby to create an API key. ATS Integration is included on the Enterprise plan. If you do not see an Org Admin section in your account, you are not an organization admin — ask someone who is or contact us to request access. If your ATS Integration page is disabled, contact us to upgrade to the Enterprise plan.
Connect the workspace
- In Ashby, go to Admin → Integrations → API Keys to create an API key. Give the key a descriptive name such as "Apployent". Select Apployent as the integration partner if it is listed. If it is not, grant the following permissions to your API key:
jobsRead,candidatesRead, andcandidatesWrite. IncludeapiKeysWriteif you want Apployent to register webhooks in Ashby. - Copy the key. Ashby displays it only once.
- In Apployent, go to Org Admin → ATS Integration, select "org-wide connection" and paste the key. The key is stored securely and cannot be viewed again. Once you save, you will see a status badge indicating whether the connection is established successfully or not.
Individual projects are not synced with Ashby by default. A project owner or editor still needs to explicitly choose a sync mode for that project. See the Project Setup section below for more details.
Additional options
To allow candidates to be automatically imported and invited (e.g., when a recruiter requests an assessment from Ashby or when a candidate reaches a stage you choose), you need to enable the optional settings below. Enabling them does not change existing projects. It just makes the option available for each project.
(Optional) Auto-import from a stage
Required only if a linked project should import candidates from a linked Ashby job when a candidate reaches a stage the project owner or editor chooses.
- If the API key already has the
apiKeysWritepermission, click Register and you are done. Apployent creates the necessary webhooks in Ashby. - If that permission is missing, create the webhooks yourself in Ashby under Admin → Integrations → Webhooks using the URL and secret shown in Apployent.
You do not need this for a manual import from ATS Sync, nor if your organization uses Assessment Ordering below.
(Recommended) Assessment Ordering
Allows Apployent projects to appear as assessments in Ashby (only projects explicitly allowed by the project owner or editor will be available). After it is enabled, recruiters can add an Apployent assessment to an interview plan and send it from a candidate profile. Sending it creates the candidate in Apployent and invites them to start the assessment. When they finish, the score appears on the Ashby candidate profile as an assessment result.
- In Apployent, generate a partner key. It is displayed once.
- In Ashby, go to Admin → Integrations → Integrations, enable Apployent, and paste the key where Ashby asks for the partner API key.
Project setup
Each project controls its own ATS setting under each project's ATS Sync page. Owners and editors can change it. Below are the sync modes available for each project. You can only choose one at a time.
No ATS sync
Leave the project standalone. You can manually add candidates to the project, invite and review them in Apployent. Ashby is not used for this job.
Link to an Ashby job
This mode ties the project to one Ashby job that the project owner or editor chooses. When enabled, you can import candidates manually from Ashby, or import them automatically when a candidate reaches a stage you choose (The "Auto-import from a stage" ioption must already be enabled by the organization admin for this to work). You can also write the completed score and a report link back to the Ashby candidate, as a native assessment when that write is available or as a note otherwise. If you map Advance and Pass to Ashby stages, those decisions will be sycned back to Ashby and move the candidate.
(Recommended) Reserve for Assessment Ordering
Choose this mode so the project appears as an assessment in Ashby. Recruiters can add it to an interview plan or send it from a candidate profile. You do not need to import the candidate first. For this to work, the "Assessment Ordering" option must already be enabled by the organization admin. The project is not tied to a single Ahsby job, which means any Ashby job can see and send this assessment. Once it is open and ready (at least one question, with evaluation setup finished), Ashby lists it under the Apployent project name, which is what recruiters search for.
- On the project's ATS Sync page, select Reserve for Assessment Ordering and save.
- (Optional) If you want this assessment to appear as a certain name, go to "Manage Project" and change the "Project Name" accordingly.
- In Ashby, add the intended Apployent assessment to the job's interview plan.
When the assessment is sent from Ashby, the candidate is added to the project and invited automatically. You can customize the invitation email in the "Interview Settings" section. When they finish, the score is written to the Ashby candidate as an assessment result.
FAQ
Apployent is not listed as an integration partner when I create the API key.
Create the key without selecting a partner, grant jobsRead, candidatesRead, and candidatesWrite, and enter the key in Apployent.
The API key was rejected.
Confirm that an Ashby admin created the key, that it includes jobsRead (Apployent uses this to validate the connection), and that the full key was copied. Then try again.
The project does not appear in Ashby's assessment list.
An organization admin must enable Assessment Ordering for the whole organization, and this project must be set to Reserve for Assessment Ordering. The project also has to be open and ready to interview: it needs at least one question, and evaluation setup must be finished. Check the project name Ashby will display.
Is Auto-import from a stage required?
No. Auto-import from a stage is an organization option, and it is required only for stage import on a linked job. Assessment Ordering does not use it.
Where do results appear in Ashby?
When the project is reserved for Assessment Ordering, the completed score is posted as an assessment result. When the project is linked to a job, the score and report link are written if sync-back is on, and Advance or Pass moves the candidate if those stages are mapped.
A candidate is missing from the project.
If the project is reserved for Assessment Ordering, the candidate is added when the assessment is sent from Ashby, not through the importer. If the project is linked to a job, confirm it is the correct job. For Auto-import from a stage, confirm it is enabled and that the candidate reached the selected stage.
The partner key was lost.
Generate a replacement in Apployent and update the Apployent integration in Ashby. The previous value cannot be recovered.
How do I disconnect Ashby?
An organization admin can disconnect Ashby from Org Admin → ATS Integration. After you reconnect, linked or reserved projects must be configured again.