---
title: "Ashby"
description: "Bring hired Ashby candidates into Pyn as upcoming employees so pre-boarding flows can start before day one."
sidebar:
  label: Overview
  order: 0
area: integrations
feature: ashby
appPath: /settings/integrations/available
lastVerified: 2026-10-22
version: "2026-10-16"
audience: admin
related:
  - integrations
  - integrations/greenhouse
  - integrations/sync-and-matching
  - flows/automations
---

The Ashby integration reads candidates who have accepted an offer and creates them as upcoming employees, with their start date, job title, department, location and hiring manager. A pre-boarding flow triggered on start date can then reach them at a personal address before their work account exists.

## Before you start

- You are an admin or owner in Pyn.
- An Ashby admin creates an API key under **Admin > API Keys** with read access to **Candidates**, **Offers** and **Organization**. Read access to **Jobs** is optional and picks up the hiring manager set on the job rather than the application. To include hires into confidential jobs, also allow access to confidential jobs and projects.

![Connect to Ashby asks for an API Key.](https://support.pynhq.com/media/integrations/ashby/integrations-ashby-connect.png)

## Connect

1. In Pyn, open **Settings** in the left navigation, then **Available** under **Integrations**.

2. Select the **Ashby** tile. The **Connect to Ashby** dialog opens.

3. Paste the **API Key**.

4. Select **Connect**. The dialog shows "Validating that API key..." while Pyn checks it.

5. On success a notice reads "Your Ashby integration has been added to Pyn. It will take a minute or two for candidate data to be pulled from Ashby."

Errors the dialog can show: "Could not verify that API key — it appears to be invalid or deactivated." / "The API key is valid but lacks the permissions needed. Grant it read access to Candidates, Offers and Organization and try again." / "Enter an Ashby API key."

## What syncs

Pyn refreshes from Ashby every 15 minutes while the integration is active. For each hired application it reads:

| Pyn property | From Ashby |
| --- | --- |
| Display name, legal name | The candidate's name |
| Work email, personal email | The candidate's work and personal contact emails |
| Start date | The latest offer version's start date |
| Job title | The application's job |
| Department, location | The job's department and location names |
| Manager | The job's hiring manager (an Ashby user) |
| Time zone | The candidate's time zone |
| Custom fields | Any workspace extension mapped to an Ashby custom field, read from the offer, then the application, then the candidate |

Hires appear in the Directory as **Upcoming** until their start date. See [Sync cadence and matching](https://support.pynhq.com/integrations/sync-and-matching/) for how they are matched to the HRIS record that arrives later.

## Test it

After the first refresh, open [Employees](https://support.pynhq.com/directory/employees/) and select the **Upcoming** view: recent hires should be listed with their start date. The integration's **History** tab shows each refresh.

## Reconnect or disconnect

- **Reconnect** from the **...** menu opens **Reconnect to Ashby** to paste a new key. "Your Ashby integration has been updated." confirms it.
- **Deactivate** pauses syncing; **Activate** resumes it.

## Troubleshooting

| What you see | What it means |
| --- | --- |
| History: "Error: Authentication failed, please reconnect" | The key was deactivated in Ashby. Create a new one and reconnect. |
| History: "Error: Insufficient Ashby permissions" | The key is missing a read scope. Grant Candidates, Offers and Organization. |
| A hire is missing | The offer is not accepted, or the job is confidential and the key cannot see it. |
| Hiring manager blank | Grant read access to Jobs, or set the hiring manager on the application. |

## Related

- [Integrations](https://support.pynhq.com/integrations/) for the catalogue.
- [Greenhouse](https://support.pynhq.com/integrations/greenhouse/) for the other ATS integration.
- [Sync cadence and matching](https://support.pynhq.com/integrations/sync-and-matching/) for how ATS and HRIS records merge.
- [Automations](https://support.pynhq.com/flows/automations/) to build a pre-boarding flow on start date.