Skip to main content

How to enable Ashby integration

By integrating Ashby, you can automatically import hired candidates to Humaans as new hires

Updated today

By reducing manual data entry, this integration ensures a smoother and more accurate hand-off between hiring and onboarding.

This guide explains the steps to creating an integration which allows you to map data from Ashby to Humaans.

Before you begin

  • To avoid the connection failing, it's essential to have the correct permissions on both Humaans and Ashby when setting up the integration.

  • Within Ashby, read permissions are required in the following scopes:

    • Candidates (candidate.info)

    • Department (department.list)

    • Jobs (jobPosting.list)

    • Offer (offer.list)

    • Hiring process metadata (customFields.list)

  • If you need to reconnect Ashby to Humaans, you'll have to reconfigure the integration.

  • You can include custom fields that map data from Ashby to Humaans user profiles. To learn more, read Adding custom fields.

  • You can map offer letters from Ashby to a document type section of your choice in the user profile.

Step 1 - Create an API key in Ashby

  1. In Ashby, open the Admin Overview, click the Integrations dropdown, and select API keys.

  2. Click + New in the top-right corner.

  3. Enter a name in the API Key field (this acts as a label).

  4. Leave Integration Partner blank (optional).

  5. Click Create API Key.

  6. In API Scopes, tick Read for the following modules:
    Jobs
    Candidates
    Hiring Process Metadata
    Organization
    Offers

  7. Click Save and continue.

  8. In API Key, click Copy and Close to copy the generated API key, because you’ll need this for Humaans.

Step 2 - Connect Ashby to Humaans

  1. Return to Humaans.

  2. Click Integrations.

  3. Click the ATS tab or scroll to find Ashby.

  4. Open by clicking Configure.

  5. Click Enable integrations.

  6. Paste the API key you just created in Ashby.

  7. Click Save.

  8. Take note of the Request URL and Secret Token generated by Humaans. You'll need them for the next step.

Step 3 - Set up a webhook in Ashby

  1. In Ashby, under Admin overview, click the Integrations dropdown menu, and click Webhooks.

  2. Click + New in the top-right corner.

  3. In Webhook Type, select Application Updated.

  4. Paste in the Request URL and Secret Token from Humaans into the relevant fields.

  5. Click Add to complete the setup and activate the integration.

Moving forward, a candidate marked as hired in Ashby will appear in Humaans in the New hires tab.

Choose what data to import from Ashby

To check what data is mapping from Ashby and where to in Humaans, follow these steps:

  1. Click Integrations.

  2. Click the ATS tab or scroll to find Ashby.

  3. Open by clicking Configure.

  4. Click Configuration.

  5. After making changes to data fields, click Save.

Ashby data fields are displayed on the left-hand side and Humaans target fields are on the opposite side.

When you configure data from Ashby to Humaans, a list of data fields for mapping will appear by default. Some of these fields aren’t clickable because they are required. Other fields aren’t required and can be toggled on and off as needed.

Default data fields that map from Ashby to Humaans

Below is the default list of fields that are imported from Ashby into Humaans:

Ashby field

Humaans field

Required?

Employment start date

Employment start

Required

First name

First name

Required

Middle name

Middle name

Optional

Last name

Last name

Required

Personal email

Personal email

Required

Personal phone number

Personal phone

Optional

Title

Job title

Required

Department

Department

Optional

Hiring manager

Reporting to

Optional

Job location

Location

Optional

Base salary

Salary

Optional

LinkedIn

LinkedIn

Optional

Twitter

Twitter

Optional

Adding custom fields

Custom data fields are denoted with a grey background and have a dropdown menu of options to allow for greater flexibility. Choose which Ashby data fields in Candidate and Offer sections map to Humaans and where in the user profile. Pick target fields across different sections such as Basics, Job role, Compensation, and Employment.

To add more custom fields for mapping other data, click Add mapping in the bottom-left corner.

Mapping offer letters from Ashby to Humaans

In the Configuration panel, under Documents, you can enable offer letters to map from Ashby to Humaans.

To choose which Document type the offer letter will map to in Humaans, click the Humaans dropdown on the right-hand side to select the document type.

Adding new hires as members

When a prospect candidate becomes a new hire in Ashby, they are added to Humaans automatically.

Candidates imported from Ashby will appear in the New hires tab. This gives you a chance to review the new hire and their information before adding them as an active member to Humaans.

To view the information of the new hire, click Add member.

Deleting new hires

To remove a new hire, open their user profile, and click Delete new hire at the bottom of the left-hand side menu. You'll be asked to confirm before deleting.

Reconnecting Ashby integration

If you need to reconnect your Ashby integration at any point, you will need to reconfigure your data fields.

To update the integration configuration, follow these steps:

  1. In Ashby, go to API keys.

  2. In the Active keys list, select Humaans integration.

  3. Beside Hiring Process Metadata, tick Read.

  4. Click Save.

That's it - your data fields from Ashby will continue mapping to Humaans! To change what data maps over, read this section of the guide.

Did this answer your question?