# Ashby for Docusign IAM

> Connect Ashby to your Docusign agreement workflows. Read candidates, job considerations, jobs and offers to pre-fill offer letters, create or update candidates and job considerations, add notes, and file the signed document under the candidate's Other Files in Ashby.

- Web page: https://fluidlabs.com/documentation/ashby-for-docusign-iam
- Published by: Fluidlabs
- Status: Live on the Docusign App Center
- Docusign App Center listing: https://apps.docusign.com/app-center/app/9012758e-43a8-44d0-b2dc-3ca84a727d4a
- App page: https://fluidlabs.com/integrations/ashby-for-docusign-iam
- Last updated: 2026-10-12
- Support: docusign-support@fluidlabs.com

## Contents

- [Quick Start](https://fluidlabs.com/documentation/ashby-for-docusign-iam#1-quick-start)
- [Implementation Guide & Known Behaviors](https://fluidlabs.com/documentation/ashby-for-docusign-iam#2-implementation-guide--known-behaviors)
- [Installation and Configuration](https://fluidlabs.com/documentation/ashby-for-docusign-iam#3-installation-and-configuration)
- [How to Use the App](https://fluidlabs.com/documentation/ashby-for-docusign-iam#4-how-to-use-the-app)
- [Read from Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#5-read-from-ashby)
- [Writeback to Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#6-writeback-to-ashby)
- [File Upload to Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#7-file-upload-to-ashby)
- [FAQ & Troubleshooting](https://fluidlabs.com/documentation/ashby-for-docusign-iam#8-faq--troubleshooting)

---

## 1. Quick Start

### 1. Install the App

- Open the [**Docusign App Center**](https://apps.docusign.com/app-center/extensionapps) and search for **Ashby**.
- Open the **Ashby** app card, click **Install App**, then **Install and Authorize** on the consent screen.

### 2. Create a Connection

- Ask an Ashby **Organization Admin** for an API key created under **Admin → Integrations → API Credentials** with the permissions listed in [Creating the Ashby API Key](https://fluidlabs.com/documentation/ashby-for-docusign-iam#3-installation-and-configuration).
- On the installed app page, click **Connect Account**.
- Choose the connection visibility (**Private** or **Shared**), give the connection a name, and click **Log In**.
- In the connect window, click **Allow**, paste the API key and click **Continue to Docusign**.

### 3. Create a Workflow

- In Docusign, open **Workflow Manager** and create a workflow.
- Choose your preferred workflow start type.
- Add an Ashby step: **Read from Ashby**, **Writeback to Ashby**, or **File Upload to Ashby**.

### 4. Available Actions

- [**Read from Ashby**](https://fluidlabs.com/documentation/ashby-for-docusign-iam#5-read-from-ashby): pull a Candidate, Job Consideration, Job or Offer into your workflow to pre-fill an offer letter.
- [**Writeback to Ashby**](https://fluidlabs.com/documentation/ashby-for-docusign-iam#6-writeback-to-ashby): create or update a candidate or a job consideration, or add a note to a candidate.
- [**File Upload to Ashby**](https://fluidlabs.com/documentation/ashby-for-docusign-iam#7-file-upload-to-ashby): file the signed document under the candidate's **Other Files**.

### 5. Key Things to Know

- Every later step addresses a record by its **Record ID**, the identifier Ashby gives each record (for example `3ae2b801-19f6-41ef-ad28-214bd731948f`). The Read and Writeback steps return it.
- A **Job Consideration** is a candidate's application to one job: the record that carries the interview stage. Ashby's API calls it an application.
- A search matches exact values with **Equal to**, combined with **AND**. Letter case and extra spaces do not matter; accents do.
- This app is separate from Ashby's own built-in Docusign integration (Admin → Integrations → DocuSign), which sends offers from Ashby. This app lets Docusign workflows read and write Ashby data and file signed documents into Ashby.


## 2. Implementation Guide & Known Behaviors

The app works with five objects:

| Object | What the app can do | Fields |
| --- | --- | --- |
| Candidate | Read, create, update | 24 |
| Job Consideration | Read, create, update | 23 |
| Job | Read | 16 |
| Offer | Read (the latest version) | 12 |
| Note | Create, always on a candidate | 3 |

Field labels match the Ashby screens. A label ending in **(Searchable)** marks a field a Read step can filter by; Record ID can always be used. Custom fields are not part of this version. After an app update that adds fields, choose **Reload Objects** on the connection under **Manage Connections** so the steps show the new list.

### Building Workflows

- Read a candidate with a **Read from Ashby** step filtered by Email, then use the **Record ID** it returns in every later step: Update, Note (Candidate Record ID), Job Consideration (Candidate Record ID) and File Upload (the subfolder).
- Read a job consideration by **Candidate Record ID** (or Candidate Email) **AND Job Record ID**. By Candidate Record ID alone, the step returns every job consideration of that candidate, across all jobs.
- **Update or Create keyed on Email is safe.** A repeated run finds the candidate and updates it. A candidate the connection just created or updated is found by its Name or Email at once, even before Ashby's own search knows it (see [Searching for a Record](https://fluidlabs.com/documentation/ashby-for-docusign-iam#2-implementation-guide--known-behaviors)).
- A Read step that finds no record does not stop the workflow. Its variables are empty.
- The Writeback step returns the **Record ID** of the record it created or updated. Use it in a later Note or File Upload step. A Note step returns the note's Record ID, not the candidate's.
- Notes, uploaded files and other changes appear in Ashby as made by the API key the connection uses (Ashby's integration identity), not by a person.

### Writeback Behaviors

#### Updating a candidate

| Topic | Behavior |
| --- | --- |
| Name | Asked for whenever the step can create a candidate (**Create**, **Update or Create**). With **Update or Create** it replaces an existing candidate's Name only when **Overwrite if field value exists** is ticked under it. With **Update** the step shows only the fields you tick, so Name is not needed. |
| Other mapped fields | Always written. An update that repeats the current values writes nothing and succeeds. |
| Empty values | Ignored. A field cannot be cleared from a workflow. An update where every value is empty is refused. |
| Email | A value that is already one of the candidate's addresses changes nothing. A new value becomes the primary email; the previous primary is kept as an other address when the candidate had none, and dropped when the candidate already has other addresses (Ashby's rule). |
| Other Email Addresses | Never removes an address. Ashby's API can only replace a candidate's other addresses with one address, so an update adds one new address, and only to a candidate who has no other address yet (the first one, when several are mapped). An address Ashby cannot add is skipped: the step writes everything else it carries. Only a step that carries nothing but such addresses is refused. Add those in Ashby. |
| Phone, Website | Phone replaces the candidate's primary phone number and Website replaces the website. Other phone numbers stay. Ashby itself may reorder the query parameters of a stored Website when the candidate's City, Region or Country is updated, so do not keep a link whose signature depends on their order in Website. |
| City, Region, Country | Ashby looks the three up together as one place and stores its own names (`Kraków` for `Krakow`, `Lesser Poland Voivodeship` for `Lesser Poland`). A City mapped alone moves to its own Region and Country; a City of the same Region keeps it. A Region or a Country mapped alone drops the stored parts that are not in it. A place Ashby cannot find (an unknown City, an approximate Region name) leaves the location as it was. Map the three together when you have them. |
| Tags | Only added, never removed, and never created: tags are created in Ashby. A tag that does not exist is skipped, and the step writes the tags that exist and everything else it carries. Only an update that carries nothing but tags that do not exist is refused. Separate tags with `;` (a comma is part of a tag); a tag whose name contains a semicolon cannot be written or searched. |
| Source, Credited To Email | A source name that is active in Ashby (or `<Source Type>: <Source>` when two source types share a name); the email of an active user of your Ashby account (Ashby shows the user's name). |
| LinkedIn URL, GitHub URL, Website | Web addresses; `https://` may be left out. Ashby files links by site, so LinkedIn URL must point to linkedin.com and GitHub URL to github.com (subdomains count); another site's address is refused. |
| Location, Timezone, Current Job Title, Current Employer, Source Type, Credited To Name | Read only. Mapping one next to a writable field is refused and nothing is written. |
| Ashby notifications | Followers are notified the same way as for an edit in Ashby. |

#### Creating a candidate

Name is required. On create, the whole list of Other Email Addresses is stored, and every tag that exists in Ashby is added; a tag that does not exist is skipped and the candidate is still created. A create whose follow-up Ashby refused reports the created Record ID: fix the field with an Update step on that Record ID, and do not re-run the Create step.

A created candidate is on no job: Ashby lists a candidate on a job only through a job consideration, so a workflow that creates a candidate for a job adds a **Job Consideration** step (Create, with the candidate's Record ID and the Job Record ID) after the Candidate step. A Create does not check whether the Email is already in use (Ashby allows several candidates with one address), so a workflow that may run again for the same person uses **Update or Create** keyed on Email.

#### Job considerations

| Topic | Behavior |
| --- | --- |
| Create | Candidate Record ID and Job Record ID are required. Without a Current Interview Stage the job consideration lands in the job's first Lead stage. A second job consideration for a candidate who already has an active one on the same job is refused by Ashby: update the existing one instead. |
| Current Interview Stage | A stage of the job's interview plan, by its title (letter case ignored); an unknown stage is refused and the message lists the plan's stages. On update, the move is applied after the other fields. A move to a stage that is not Archived reactivates an archived job consideration (see Archive Reason). |
| Outcome | Read only. It follows the stage: move the job consideration to a Hired stage or to an Archived stage instead. |
| Archive Reason | Needed for a move to an Archived stage. **Mapped on its own, it archives the job consideration**: with Current Interview Stage left empty, the step moves it to the Archived stage of its interview plan with that reason, as Ashby's own Archive button does. When the plan has several Archived stages the step is refused and names them: map Current Interview Stage to the one you want, together with the reason. An Archive Reason next to a stage that is not Archived is refused, and the reason of an already archived job consideration cannot be changed from a workflow (change it in Ashby). **A stage move reactivates an archived job consideration**: an Update step that always maps Current Interview Stage un-archives a rejected candidate when it runs again, so map the stage only in steps meant to move. A Read of an archived job consideration returns the Archived stage as Current Interview Stage, `Archived` as Current Interview Stage Type and as Outcome, the Archive Reason and Archived At. |
| Hired | When your Ashby account requires an opening for every hire (Admin → Openings → "Require Openings for Hires"), Ashby cannot pick the opening through the API: the step reports that nothing was changed, and the hire is completed in Ashby (record the offer as accepted, or Change Stage → Hired with the opening). A design that works everywhere: file the signed document, add the note or tag, and move the job consideration to the stage before Hired. |
| Interview plans | Moving a job consideration whose interview plan is not the job's default plan needs the optional **Interviews - Read** permission on the key. |
| Automations | A move to Hired or to an Archived stage can start the automations your Ashby account runs on those stages (an HRIS push, an opening marked filled, emails). Check them before you automate the move. |
| Candidate and job | A job consideration cannot be moved to another candidate or another job. |

#### Notes

The **Note** object is create-only and always belongs to a candidate:

| Field | What to know |
| --- | --- |
| Candidate Record ID | Required. The candidate's Record ID from a Read or Writeback step. |
| Note Content | Required. Stored as typed, as plain text: HTML is not rendered. Line breaks are kept when the value comes from a variable that contains them (an envelope field, an earlier step's text); text typed directly into the field in the workflow builder is a single line. Ashby shows the API key's name as the author. |

Ashby ties notes to the candidate, not to a job consideration.

### Searching for a Record

#### Searchable fields

| Object | Fields |
| --- | --- |
| Candidate | Record ID, Name, Email |
| Job Consideration | Record ID, Candidate Record ID, Candidate Email, Job Record ID, Job Title |
| Job | Record ID, Job Title, Requisition ID, Job Status |
| Offer | Record ID, Job Consideration Record ID, Acceptance Status |

Any other field in the rule stops the step with a message naming the fields that can be searched. Notes cannot be searched.

#### Matching

- **Equal to only, combined with AND.** The other operators and OR are refused; split an OR rule into separate Read steps.
- **Letter case and extra spaces never matter. Accents do:** `ADA@EXAMPLE.COM` and `ada  lovelace` match, `Zoe` does not find `Zoë`. A partial value is not a match.
- **Email** matches the candidate's primary **or any other** address. The same goes for Candidate Email on a job consideration. A value that is not a complete email address is refused with a message quoting the value.
- **Record ID** takes Equal to only and overrides every other condition in the rule. A Record ID that matches nothing, or is not an Ashby id, returns nothing.
- **Job Status** and **Acceptance Status** take a value from Ashby's list (Draft, Open, Closed, Archived; Accepted, Declined, Pending, Created, Cancelled), in any letter case.
- **One value per condition.** A `;` separates two values and stops the step, except in Job Title, where it is part of the title. A comma is part of the value.
- A **Job Consideration search by Job Title** must match exactly one job. A title shared by several jobs is refused: search by Job Record ID instead.
- A Job read without a condition returns every job, Draft jobs included.
- **Ashby's search lags a change by about half a minute.** A candidate created or renamed in Ashby is found by Name or Email after that. A candidate this connection created or updated is remembered for five minutes and found at once, so a Create-or-Update run twice for the same new person updates the first candidate instead of creating a second one. Search by Record ID is not affected.
- **When several records match, their order is fixed:** candidates newest first; a candidate's job considerations with the active ones first, then newest first; jobs Open, Draft, Closed, Archived, then newest first. **A single record** takes the first one. Identify a person by Email or Record ID, and a job consideration by Candidate Record ID AND Job Record ID, rather than by Name alone.
- A result holds up to 25 records by default. A search Ashby cannot complete within the step's time is refused with a message naming the condition to add (for example Email next to a common Name); the step never returns a partial list.

### Reading Record Data

| Type | Reads as |
| --- | --- |
| Date and time | UTC: `2026-09-23T10:15:00.000Z` |
| Offer Start Date (a calendar date in Ashby) | 12:00 UTC on that date: `2026-12-15T12:00:00.000Z`. Use the date part in a document. |
| Offer Decided At | Ashby's stored instant: for an offer accepted in Ashby, 00:00 UTC of the decision day (`2026-12-01T00:00:00.000Z`). Use the date part; a time-zone conversion can show the previous day. |
| Lists (Other Email Addresses, Other Phone Numbers, Tags, several hiring-team members) | One text, values separated by `; ` |
| Closed lists | Ashby's wording: Job Status `Open`, Employment Type `Full time`, Current Interview Stage Type `Application Review`, Outcome `Active`, Acceptance Status `Accepted` |
| Salary | A number; Salary Currency holds the code, for example `USD` |

- **Phone** and **Email** are the primary number and address; the others are under Other Phone Numbers and Other Email Addresses. When Ashby marks none as primary, the first one listed is shown as primary.
- **Hiring Manager, Recruiter and Recruiting Coordinator** read the hiring-team members with that role title; several holders are joined with `; `, so map an Emails field to a recipient only when the role has one holder.
- **Current Job Title** and **Current Employer** are filled by Ashby from resume parsing or an import.
- An Offer reads its latest version (Start Date, Salary, Salary Currency, Approval Status), and the **Candidate Name**, **Candidate Email** and **Job Title** of its job consideration: an offer letter needs one Read step, an Offer by Job Consideration Record ID. The three cannot be used in a rule.
- A **Job Consideration** reads the application, not the offer: after a candidate declines an offer it is still Active in its Offer stage. The offer's own state is on the Offer object (Acceptance Status, Offer Status).
- **City, Region and Country** read the place Ashby resolved. **Location** is Ashby's summary text and its shape depends on how the location was entered (`Kyiv, Ukraine` or `Poland, Lesser Poland, Kraków`), and right after an update it can still show the previous text while the three already read the new place: use City, Region and Country in documents, Location for display only.
- **Source** and **Source Type** are two fields (`Campus Recruiting Events` and `Other`) where Ashby's screen shows one label (`Other: Campus Recruiting Events`).
- Empty fields are left out of the result.

### Confidential Jobs

Without **"Allow access to confidential jobs and projects?"** under Other Permissions on the API key, confidential jobs, their job considerations and their candidates are invisible to the app: searches return no match and a Create-or-Update step can create a duplicate candidate. Tick it on the key if your workflows touch confidential jobs.


## 3. Installation and Configuration

### Prerequisites

- An **Ashby** account, and an Ashby **Organization Admin** who can create an API key.
- A **Docusign** account with admin rights to install and manage apps in the App Center.

### How to Install the App

- Open the [**Docusign App Center**](https://apps.docusign.com/app-center/extensionapps) and search for **Ashby** in the search bar.

  ![Docusign App Center search results showing the Ashby extension app by Fluidlabs.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/app-center-search.webp)

- Click the **Ashby** app card to open its detail page, then click **Install App**.

  ![The Ashby app page in the Docusign App Center with the Install App button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/app-install.webp)

- Review the access the app requests and click **Install and Authorize**.

  ![The Install and authorize Ashby app screen listing the requested access, with the Install and Authorize button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/install-authorize.webp)

The app now appears with an **Installed** status.

### Creating the Ashby API Key

The connection uses an Ashby API key. An **Organization Admin** creates it in Ashby:

- Go to **Admin → Integrations → API Credentials** and click **+ New**.
- Name it **Docusign**, leave Integration Partner empty, and click **Create API Key**.
- On the **API Scopes** step, in the **Endpoint Permissions** table (one row per module with a **Read** and a **Write** column), tick **Read** for **Jobs**, **Candidates**, **Hiring Process Metadata**, **Organization**, **Offers** and **Api Keys**, and **Write** for **Candidates**. The connect window lists the same seven as Candidates - Read, Candidates - Write, Jobs - Read, Hiring Process Metadata - Read, Organization - Read, Offers - Read and Api Keys - Read. Leave every other module unticked.
- Optional: tick **Read** for **Interviews** if your workflows move job considerations whose interview plan is not the job's current default plan.
- Optional, under **Other Permissions**: tick **Allow access to confidential jobs and projects?** if your workflows use confidential jobs. Leave **Allow updating application history?** and **Allow on-behalf-of requests?** unticked.
- Click **Save and Continue** and copy the key. Ashby shows it only once.

  ![The Endpoint Permissions table of an Ashby API key with Read ticked for Jobs, Candidates, Hiring Process Metadata, Organization, Offers and Api Keys, Write ticked for Candidates, and the Other Permissions left unticked.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/ashby-api-key-scopes.webp)

A key's permissions can be changed later in API Credentials without creating a new key, and the change applies to the connection at once.

### Connecting Your Account

- On the installed app page, click **Connect Account**.

  ![The installed Ashby app page showing the Connect Account button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/connect-account.webp)

- **Connection Visibility**: choose how the connection is shared:

  - **Private**: accessible only by you in Docusign.
  - **Shared**: accessible by multiple users or the whole team.

  ![The Connection Visibility step with Private and Shared options.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/connection-visibility.webp)

- **Name Connection**: enter a name. It appears in workflow steps, so make it easy to identify. Click **Log In**.

  ![The Name Connection step with a connection name entered.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/name-connection.webp)

- The connect window opens. It lists what the app can do with your Ashby account and, on the left, the steps for creating the key. Click **Allow**.

  ![The Ashby connect window asking Allow access?, listing read, create and update, and file upload, with Deny and Allow buttons.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/ashby-consent.webp)

- Paste the Ashby API key and click **Continue to Docusign**.

  ![The Connect Ashby step with the Ashby API key field and the Continue to Docusign button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/ashby-api-key.webp)

The key is checked with Ashby before the connection is saved. A missing permission is named in the window; add it to the key in Ashby and paste the same key again. The key is encrypted and never shared with Docusign.

The connection is added and ready to use in workflow steps. Each connection works with the Ashby account the key belongs to.

### Managing Connections

On the Ashby app page, open the **Manage** dropdown.

![The Manage dropdown on the Ashby app page showing New Connection, Manage Connections, and Manage Apps.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/manage-connections-menu.webp)

Select **Manage Connections** to see every connection.

![The Ashby connections list showing a connection with an Active status and the New Connection button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/connections-list.webp)

Use the three-dot (⋮) menu next to a connection:

![The connections list with the three-dot menu open showing Edit connection name, Reconnect, Reload Objects, and Delete Connection.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/connections-actions-menu.webp)

- **Edit connection name**: rename the connection.
- **Reconnect**: paste a key again. Use it when a key was disabled, deleted or replaced in Ashby. Permission changes on the same key never need a reconnect.
- **Reload Objects**: refresh the available record types and fields. Use it once after an app update that adds fields, such as the three Offer fields added in October 2026; running workflows are not affected.
- **Delete Connection**: remove the connection. ⚠️ This may break workflows that use it.

### Adding a New Connection

Use **Manage → New Connection** on the app page, or **+ New Connection** on the Connections page. Each connection appears separately in workflow steps and works with the Ashby account of the key pasted into it.

### Revoking Access from Ashby

In Ashby, open **Admin → Integrations → API Credentials** and disable or delete the **Docusign** key. Every Docusign connection using that key then stops working until it is reconnected with a new key.


## 4. How to Use the App

### Create a Workflow

- Log in to Docusign and go to **Agreements → Workflows**.
- Click **Create Workflow**.

  ![The Docusign Workflows screen with the Create Workflow button.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/workflow.webp)

- Build your workflow using the available steps, including the Ashby actions.
- Publish the workflow when it is ready.

### Available Ashby Actions

Click **+ Add Step** and search for **Ashby**:

![The Add New Step dialog with "Ashby" searched, showing File Upload to Ashby, Writeback to Ashby, and Read from Ashby.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/add-step-actions.webp)

- **Read from Ashby**: fetch a **Candidate**, **Job Consideration**, **Job** or **Offer** and expose its fields as workflow variables. See [Read from Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#5-read-from-ashby).
- **Writeback to Ashby**: create or update a **Candidate** or a **Job Consideration**, or create a **Note** on a candidate. See [Writeback to Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#6-writeback-to-ashby).
- **File Upload to Ashby**: store a document from the workflow under the candidate's **Other Files**. See [File Upload to Ashby](https://fluidlabs.com/documentation/ashby-for-docusign-iam#7-file-upload-to-ashby).

A typical hiring flow:

1. **Read from Ashby**: find the candidate, and the job consideration or offer for the offer details.
2. **Prepare eSignature Template**: pre-fill the offer letter.
3. **Send Documents for Signature**.
4. **File Upload to Ashby**: file the signed offer under the candidate's **Other Files**.
5. **Writeback to Ashby**: add a note, tag the candidate, or move the job consideration to the next stage.

Jobs and offers are read-only. There is no writeback to a job or an offer.


## 5. Read from Ashby

The **Read from Ashby** step retrieves a record and exposes its fields as workflow variables.

### Start the Workflow

The example below starts the workflow **From an API Call** with one **Text** variable, `candidate_email`, that carries the candidate's email address. Any start type works: with a web form, use the form's email field wherever this example uses `candidate_email`.

![The Add workflow start panel: From an API Call with a Text variable named candidate_email.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-workflow-start.webp)

### 1. Add the Read Step

On the workflow canvas, click **+ Add a step** below the start.

![The workflow canvas with the Add a step button below Start Workflow.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-add-step-canvas.webp)

Search for **Ashby** and select **Read from Ashby**.

![The Add New Step dialog with Read from Ashby highlighted.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-add-step-search.webp)

### 2. Configure Connection and Object

- **Connection**: select the connection you created during [installation](https://fluidlabs.com/documentation/ashby-for-docusign-iam#3-installation-and-configuration).

  ![The Read step Connection dropdown showing the Ashby connection.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-configure-connection.webp)

- **Ashby object**: choose **Candidate**, **Job Consideration**, **Job** or **Offer**. This example uses **Candidate**.

  ![The Ashby object dropdown showing Candidate, Job Consideration, Job and Offer.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-configure-object.webp)

Click **Next**.

### 3. Select Fields

Click **Add or Remove Fields** and tick the fields your workflow needs. The selected fields become workflow variables for later steps.

![The field browser listing Candidate fields with checkboxes, the searchable ones marked (Searchable).](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-fields-browser.webp)

Available fields:

**Candidate:** Record ID, Name, Email, Other Email Addresses, Phone, Other Phone Numbers, LinkedIn URL, GitHub URL, Website, Location, City, Region, Country, Timezone, Current Job Title, Current Employer, Tags, Source, Source Type, Credited To Email, Credited To Name, Candidate Profile URL, Added At, Updated At.

**Job Consideration:** Record ID, Candidate Record ID, Candidate Name, Candidate Email, Job Record ID, Job Title, Current Interview Stage, Current Interview Stage Type, Outcome, Archive Reason, Archived At, Source, Source Type, Credited To Email, Credited To Name, Hiring Manager Names, Hiring Manager Emails, Recruiter Names, Recruiter Emails, Recruiting Coordinator Names, Recruiting Coordinator Emails, Started At, Updated At.

**Job:** Record ID, Job Title, Requisition ID, Job Status, Employment Type, Team, Location, Hiring Manager Names, Hiring Manager Emails, Recruiter Names, Recruiter Emails, Recruiting Coordinator Names, Recruiting Coordinator Emails, Opened At, Closed At, Created At.

**Offer:** Record ID, Job Consideration Record ID, Candidate Name, Candidate Email, Job Title, Acceptance Status, Offer Status, Approval Status, Start Date, Salary, Salary Currency, Decided At.

Click **Next**.

### 4. Identify the Record

Create a rule that tells the step which record to read. In this example, match the candidate's **Email** to the `candidate_email` start variable:

- **Ashby field:** Email (Searchable)
- **Operator:** Equal to
- **Workflow field:** `candidate_email`

![The record-matching rule: Email equals the candidate_email variable, with A single record selected.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-identify-record.webp)

Under **How many records should this step return?**, pick one:

- **A single record**: the first record that matches.
- **Multiple records**: up to five.

Click **Done** on the rule, then use **preview this step** to check it against live data, and click **Apply**.

![The preview of a Read step showing one candidate's fields as read from Ashby.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/read-preview.webp)

Which fields and operators a rule can use is under [Searching for a Record](https://fluidlabs.com/documentation/ashby-for-docusign-iam#2-implementation-guide--known-behaviors).

To read the candidate's job consideration for one job, add a second Read step on **Job Consideration** with two conditions: **Candidate Record ID** Equal to the first step's Record ID, AND **Job Record ID** Equal to the job's Record ID. Its **Current Interview Stage** and hiring-team fields are then available to the offer letter.


## 6. Writeback to Ashby

The **Writeback to Ashby** step creates or updates a candidate or a job consideration, or adds a note to a candidate.

### 1. Add the Writeback Step

On the workflow canvas, click **+ Add a step** where the writeback belongs, then search for **Ashby** and select **Writeback to Ashby**.

![The Add New Step dialog with Writeback to Ashby highlighted.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-add-step-search.webp)

### 2. Configure Connection, Object, and Write Setting

- **Connection**: select your Ashby connection.

- **Ashby object**: choose **Candidate**, **Job Consideration** or **Note**. This walkthrough uses Candidate.

  ![The Ashby object dropdown for the Writeback step showing Candidate, Job Consideration and Note.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-configure-object.webp)

- **Write settings**:

  - **Update or Create**: updates the matching record, or creates one if the rule finds nothing.
  - **Update**: updates an existing record only. This walkthrough uses Update.
  - **Create**: always creates a record.

  ![The Write settings options: Update or Create, Update, and Create.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-write-settings.webp)

Click **Next**.

### 3. Map Fields

Click **Add or Remove Fields** and tick the fields you want to write.

![The field browser listing the writable Candidate fields with checkboxes.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-fields-browser.webp)

Each selected field gets its own row. Map it to the workflow variable that supplies the value, or type a value.

![The Writeback step with Email mapped to the candidate_email variable and Tags set to Offer signed.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-map-fields.webp)

**Writable Candidate fields:** Name\*, Email, Other Email Addresses, Phone, LinkedIn URL, GitHub URL, Website, City, Region, Country, Tags, Source, Credited To Email.

_\* Name is required when the step can create a candidate._

In this example the step updates the candidate the Read step found: **Email** comes from `candidate_email` (an address the candidate already has changes nothing); **Tags** is set to **Offer signed**, a tag that exists in Ashby. With **Update**, only the fields you tick are listed.

With **Update or Create** or **Create**, the step also lists **Name**, which is required. Under it, **Overwrite if field value exists** decides whether an existing candidate's Name is replaced.

![The Update or Create form listing Name (Searchable) as required, with the Overwrite if field value exists checkbox.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-name-required.webp)

⚠️ **Map from the right source.** The variable picker also lists the output of your **Read from Ashby** step. Mapping from there writes the original values back unchanged. Map new values from the step that collected them, such as a start variable or a web form.

Click **Next**.

### 4. Identify the Record

Match the candidate by **Record ID** or by **Email**:

- **Ashby field:** Record ID
- **Operator:** Equal to
- **Workflow field:** the **Record ID** of the Read from Ashby step

![The record-matching rule for Writeback: Record ID equals the Read step's Record ID.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-identify-record.webp)

Click **Apply**.

With **Update or Create** keyed on **Email**, an email that no candidate has yet creates the candidate; running the workflow again with the same email updates it.

### Updating a Job Consideration

Select **Job Consideration** as the Ashby object and **Update** as the write setting to move a candidate's application to another stage. Tick **Current Interview Stage** and enter the stage's title as it appears in the job's interview plan.

![The Job Consideration step in Update mode with Current Interview Stage set to Hired.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/writeback-job-consideration.webp)

**Writable Job Consideration fields:** Candidate Record ID\*, Job Record ID\*, Current Interview Stage, Archive Reason, Source, Credited To Email.

_\* Required when the step creates a job consideration._

Identify the job consideration by its **Record ID** (from a Read step on Job Considerations), or by **Candidate Record ID** AND **Job Record ID**. A move to an Archived stage needs an **Archive Reason** in the same step, and an **Archive Reason** mapped on its own archives the job consideration (it moves to the Archived stage of its interview plan). A stage move on an archived job consideration reactivates it. What a move to **Hired** needs is under [Job considerations](https://fluidlabs.com/documentation/ashby-for-docusign-iam#2-implementation-guide--known-behaviors).

### Writing a Note

Select **Note** as the Ashby object. **Create** is the only write setting.

![The Note object with Create as the only write setting.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/note-write-settings.webp)

Map **Candidate Record ID** and **Note Content**, both required.

![The Note fields: Candidate Record ID mapped to the Read step's Record ID, and Note Content.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/note-fields.webp)

For Candidate Record ID, use the **Record ID** of a Read from Ashby step on Candidates or of a Candidate Writeback step. The note appears in the candidate's **Notes** in Ashby, as plain text.

![Notes on the candidate in Ashby; the newest was added by the workflow.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/note-in-ashby.webp)


## 7. File Upload to Ashby

The **File Upload to Ashby** step files a document produced earlier in the workflow under the candidate's **Other Files** in Ashby. Maximum size is 30 MB.

### 1. Add the File Upload Step

Add a step after signing completes, search for **Ashby**, and select **File Upload to Ashby**.

![The Add New Step dialog with File Upload to Ashby highlighted.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-add-step-search.webp)

### 2. Select the File

Choose the file or envelope from an earlier step, for example the **Combined Envelope File** from **Send Documents for Signature**.

![The file picker showing the envelope files of the signing step.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-select-file.webp)

> An empty list means no earlier step in the workflow produced a file.

### 3. Choose the Drive

- **Select connection**: your Ashby connection.
- **Select drive**: the app has one drive, **Candidate Other Files (put the Candidate Record ID in a new subfolder)**.

  ![The Select drive dropdown with the Candidate Other Files drive.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-select-drive.webp)

### 4. Point the Folder at the Candidate

The subfolder holds the candidate's **Record ID**. Ashby keeps a candidate's files directly on the candidate, so the path is the drive and the Record ID only; the app uses the value to find the candidate.

- Click **Add Folder**, open the **Select folder** dropdown and pick **New Subfolder**.

  ![The Select folder dropdown open with the New Subfolder option.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-new-subfolder.webp)

- In the **New folder** dialog, click **Add Variable**, choose the step that returns the candidate, select **Record ID** and click **Add**.

  ![The variable picker with Record ID selected from the Read from Ashby step.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-add-variable-record-id.webp)

- **Select folder** now shows the Record ID variable. Click **Next**.

  ![The File Upload location with the connection, the Candidate Other Files drive, and a Record ID variable as the folder.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-location-set.webp)

A Read from Ashby step on Candidates or a Candidate Writeback step returns the candidate's Record ID. A Job Consideration's Record ID is refused with a message pointing at its Candidate Record ID field; a Note's or a Job's Record ID is not a candidate. A folder before or after the Record ID is refused as well.

### 5. Name the File

Build the file name from **Add Text** and **Add Variable**. A date or time variable keeps repeat runs apart.

![The file name step with text and variable chips.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-file-name.webp)

The name needs no extension: Docusign adds it, so `Offer Letter` is stored as `Offer Letter.pdf`. A name typed as `Offer Letter.pdf` is stored the same way: the app drops the doubled extension.

In a value filled in from a variable, characters other than letters, digits, spaces and `. - _ # ' , & ( ) +` are replaced with `_`, so a time `10:15:00` is stored as `10_15_00`. Accented and non-Latin letters are kept.

Click **Apply**.

### 6. Verification

After the workflow runs, the document appears on the candidate in Ashby under **Summary → Other Files**, without a file category and not private.

![The candidate's Other Files in Ashby showing the signed offer letter PDF.](https://fluidlabs.com/images/documentation/ashby-for-docusign-iam/file-upload-verification.webp)

Sending the same file to the same candidate again within 10 minutes files it once. If the envelope was sent through Ashby's own built-in Docusign integration, Ashby already files the signed copy itself; use this step for agreements that start in Docusign.


## 8. FAQ & Troubleshooting

**A step failed and Docusign only shows the start of the message.**
> Maestro's run monitor shows a failed step as "Something went wrong" (`ActionFailed`) without the app's text, and Docusign's own summary is only the beginning of it. The app's full message is in the step's response; it names the field and what to do. The causes, in the order to check them from the step's mapping: a field that cannot be searched, an operator other than Equal to, an OR rule, a value outside Ashby's list (Job Status, Acceptance Status, a stage, a source, a tag, an archive reason), an Archive Reason next to a stage that is not Archived, a read-only field in a write, a Record ID that is not a candidate's, or a folder around the Record ID in a File Upload.

**The connect window says the key lacks a permission.**
> An Ashby Organization Admin ticks that permission on the key under Admin → Integrations → API Credentials. Then paste the same key again. Permission changes apply at once; no reconnect is needed.

**My Ashby API key was replaced or disabled.**
> Open **Manage Connections**, click **Reconnect** on the connection and paste the new key.

**A field I expect is missing from the step.**
> Open **Manage Connections**, choose **Reload Objects** on the connection (a **Reconnect** does the same), then reopen the step.

**My search does not find a candidate I just created in Ashby.**
> Ashby's search needs about half a minute before a candidate added or renamed in Ashby is found by Name or Email. Candidates this connection created or updated are found at once. Read by Record ID when you have it.

**Searching "Zoe" does not return "Zoë".**
> Accents are matched exactly. Search with the accent.

**Why can't I search by City, Tags, or a date?**
> Only the fields marked **(Searchable)** can be used in a rule, plus Record ID. Search by one of them and read the other fields from the result.

**My rule uses OR, or Contains, and the step failed.**
> The app matches exact values with Equal to, combined with AND. Split an OR rule into separate Read steps.

**A Read on Job Considerations returns several records.**
> By Candidate Record ID or Candidate Email alone, the step returns every job consideration of that candidate. Add **Job Record ID** with AND for the one job.

**My Update or Create step did not change the Name.**
> Tick **Overwrite if field value exists** under Name in the Writeback step.

**How do I clear a field?**
> Not from a workflow: empty values are ignored. Clear it in Ashby.

**A tag I mapped was not added.**
> Tags must already exist in Ashby and must not be archived; a tag that does not exist is skipped and the rest of the step is written. Create the tag in Ashby first. Separate tags with `;`. A step that carries nothing but tags that do not exist is refused with a message naming them.

**An other email address was not added, or the step says Other Email Addresses was not changed.**
> On update, the app adds one address to a candidate who has no other address yet; Ashby's API cannot add to an existing list without replacing it. An address it cannot add is skipped and the rest of the step is written; a step that carries nothing else is refused with that message. Add the address in Ashby.

**I changed the City and the location did not change.**
> Ashby could not find the place: the location is left as it was. Write the City as Ashby shows it, or map City, Region and Country together.

**The new Offer fields do not show in my step.**
> Open **Manage Connections**, choose **Reload Objects** on the connection, then reopen the step.

**A LinkedIn URL or GitHub URL is refused.**
> LinkedIn URL must be an address on linkedin.com and GitHub URL on github.com. Map another site's address to **Website**.

**The move to a stage is refused with a list of stages.**
> Current Interview Stage takes a stage of the job's interview plan, by its title. Use one of the listed titles.

**The move to Hired failed with an internal error from Ashby.**
> Your Ashby account requires an opening for every hire, which Ashby cannot pick through the API. Complete the hire in Ashby (record the offer as accepted, or Change Stage → Hired with the opening) and move the step to the stage before Hired.

**The step says the job consideration needs the Interviews - Read permission.**
> The job consideration's interview plan is not the job's current default plan. An Ashby admin ticks **Interviews - Read** on the key.

**A candidate, job or file is not found, but I can see it in Ashby.**
> It is probably on a confidential job. An Ashby admin ticks **Allow access to confidential jobs and projects?** on the key under Other Permissions.

**The file picker says no files are available.**
> No earlier step produced a file. Add the upload after **Send Documents for Signature**.

**The file did not appear on the candidate.**
> The folder has to hold the candidate's Record ID variable, from a step that runs before the upload, and nothing else. A Record ID taken from a Note step, a Job read or a Job Consideration read is not a candidate's.

**Do I type `.pdf` at the end of the file name?**
> No need: Docusign adds the extension to the name you build. If you do type it, the app stores the file with one `.pdf`.

**The signed document appears twice on the candidate.**
> The envelope was also sent through Ashby's own Docusign integration, which files the signed copy itself. Use the File Upload step for agreements that start in Docusign.

**Who appears as the author of the note or the file in Ashby?**
> The API key the connection uses (Ashby's integration identity), not a person.

---

Ashby for Docusign IAM is published by Fluidlabs. Docusign is a trademark of Docusign, Inc.
