3ae2b801-19f6-41ef-ad28-214bd731948f). The Read and Writeback steps return it.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) | 9 |
| 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 changes fields, run Reconnect under Manage Connections so the steps show the new list.
| 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. One new address is added to a candidate who has no other address yet; a candidate who already has other addresses, or several new addresses at once, is refused and nothing is written. Add those in Ashby. |
| Phone | Replaces the candidate's primary phone number. |
| City, Region, Country | Merged with the stored location: updating City alone keeps the stored Region and Country. Ashby may normalise place names. |
| Tags | Only added, never removed. Every tag must already exist in Ashby; an unknown tag is refused and never created. Separate tags with ; (a comma is part of a tag). |
| 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 Ashby user. |
| 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. |
Name is required. On create, the whole list of Other Email Addresses and Tags is stored. A create whose follow-up Ashby refused (for example an unknown tag) reports the created Record ID: fix the field with an Update step on that Record ID, and do not re-run the Create step.
| 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. |
| 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, and only settable together with that move. |
| 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. |
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 plain text. |
Ashby ties notes to the candidate, not to a job consideration.
| 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.
ADA@EXAMPLE.COM and ada lovelace match, Zoe does not find Zoë. A partial value is not a match.; 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.| 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 |
| 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 |
; , so map an Emails field to a recipient only when the role has one holder.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.
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.
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.
On the installed app page, click Connect Account.
Connection Visibility: choose how the connection is shared:
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.
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:
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.
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.
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.
Click + Add Step and search for Ashby:
A typical hiring flow:
Jobs and offers are read-only. There is no writeback to a job or an offer.
The Read from Ashby step retrieves a record and exposes its fields as workflow variables.
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.
On the workflow canvas, click + Add a step below the start.
Search for Ashby and select Read from Ashby.
Connection: select the connection you created during installation.
Ashby object: choose Candidate, Job Consideration, Job or Offer. This example uses Candidate.
Click Next.
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, Acceptance Status, Offer Status, Approval Status, Start Date, Salary, Salary Currency, Decided At.
Click Next.
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:
candidate_emailUnder How many records should this step return?, pick one:
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.
The Writeback to Ashby step creates or updates a candidate or a job consideration, or adds a note to a candidate.
On the workflow canvas, click + Add a step where the writeback belongs, then search for Ashby and select Writeback to Ashby.
Connection: select your Ashby connection.
Ashby object: choose Candidate, Job Consideration or Note. This walkthrough uses Candidate.
Write settings:
Click Next.
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.
Match the candidate by Record ID or by Email:
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.
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; what a move to Hired needs is under Job considerations.
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.
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.
Add a step after signing completes, search for Ashby, and select File Upload to Ashby.
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.
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 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.
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.
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.
A step failed and Docusign only shows the start of the message.
The app's full message is in the step's response. It names the field and what to do: 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), 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, click Reconnect on the connection, 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 wrote is refused.
Tags must already exist in Ashby and must not be archived. Create the tag in Ashby first, or remove it from the step. Separate tags with
;.
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. Add the address in Ashby.
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.