
Ashby for Docusign IAM
Get started Section 1 of 8
Quick Start
1. Install the App
- Open the Docusign App Center 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.
- 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: pull a Candidate, Job Consideration, Job or Offer into your workflow to pre-fill an offer letter.
- Writeback to Ashby: create or update a candidate or a job consideration, or add a note to a candidate.
- 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.
Reference Section 7 of 8
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).
- 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. |
| 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.COMandada lovelacematch,Zoedoes not findZoë. 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, UkraineorPoland, 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 EventsandOther) 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.
Get started Section 2 of 8
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 and search for Ashby in the search bar.
-
Click the Ashby app card to open its detail page, then click Install App.
-
Review the access the app requests and click Install and Authorize.
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.
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.
-
Connection Visibility: choose how the connection is shared:
- Private: accessible only by you in Docusign.
- Shared: accessible by multiple users or the whole team.
-
Name Connection: enter a name. It appears in workflow steps, so make it easy to identify. Click Log In.
-
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.
-
Paste the Ashby API key and click Continue to Docusign.
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.
Select Manage Connections to see every connection.
Use the three-dot (⋮) menu next to a connection:
- 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.
Use the app Section 3 of 8
How to Use the App
Create a Workflow
-
Log in to Docusign and go to Agreements → Workflows.
-
Click Create Workflow.
-
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:
- Read from Ashby: fetch a Candidate, Job Consideration, Job or Offer and expose its fields as workflow variables. See 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.
- File Upload to Ashby: store a document from the workflow under the candidate's Other Files. See File Upload to Ashby.
A typical hiring flow:
- Read from Ashby: find the candidate, and the job consideration or offer for the offer details.
- Prepare eSignature Template: pre-fill the offer letter.
- Send Documents for Signature.
- File Upload to Ashby: file the signed offer under the candidate's Other Files.
- 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.
Use the app Section 4 of 8
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.
1. Add the Read Step
On the workflow canvas, click + Add a step below the start.
Search for Ashby and select Read from Ashby.
2. Configure Connection and Object
-
Connection: select the connection you created during installation.
-
Ashby object: choose Candidate, Job Consideration, Job or Offer. This example uses Candidate.
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.
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
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.
Which fields and operators a rule can use is under Searching for a Record.
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.
Use the app Section 5 of 8
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.
2. Configure Connection, Object, and Write Setting
-
Connection: select your Ashby connection.
-
Ashby object: choose Candidate, Job Consideration or Note. This walkthrough uses Candidate.
-
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.
Click Next.
3. Map Fields
Click Add or Remove Fields and tick the fields you want to write.
Each selected field gets its own row. Map it to the workflow variable that supplies the value, or type a value.
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.
⚠️ 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
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.
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.
Writing a Note
Select Note as the Ashby object. Create is the only write setting.
Map Candidate Record ID and Note Content, both required.
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.
Use the app Section 6 of 8
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.
2. Select the File
Choose the file or envelope from an earlier step, for example the Combined Envelope File from Send Documents for Signature.
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).
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.
-
In the New folder dialog, click Add Variable, choose the step that returns the candidate, select Record ID and click Add.
-
Select folder now shows the Record ID variable. Click Next.
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 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.
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.
Reference Section 8 of 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
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.