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) | 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.
| 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. |
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.
| 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. |
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.
| 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. 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 |
; , so map an Emails field to a recipient only when the role has one holder.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.Campus Recruiting Events and Other) where Ashby's screen shows one label (Other: Campus Recruiting Events).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, Candidate Name, Candidate Email, Job Title, 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, 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.
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.
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.
Book a free 30-minute setup call with a solution consultant. Most setups finish inside the call: the connection, the field mapping, the first run. A larger setup becomes a separate engagement, with a fixed price in writing.
Tell us what happens and we take it from there. The message goes to docusign-support@fluidlabs.com.
Name the app. We answer with the app that already covers it, or a scoped plan for the connection.