A candidate is an application, not a person. Someone who applied to two jobs is two candidate records with the same name and email. See Candidates are applications.
A search can return several records for the same person, one per application. Same name, same emails, different Record ID, different Stage and Job Posting Title.
| Field | Scope |
|---|---|
| Name, Headline, Location, Email Addresses, Phone Numbers, Mobile / Work / Home Phone, Links | Changes on every application this person holds. |
| Stage, Tags | Only changes on the current application. |
Candidate: Record ID, Email Addresses, Tags, Sources, Origin, Stage, Job Posting Title.
Job Posting: Record ID, Job Title, State, Tags.
Every other field stops the workflow step.
Lever tags every application with its posting's title, team, and location, so the Tags variable holds more values than a recruiter sees on the card. A candidate tagged qa-keep on a Customer Success Manager posting returns:
Customer Success Manager; Customer Success; Remote - US; qa-keep
A search on Tags matches the automatic tags as well as the ones a recruiter set.
| Field | Behavior on update |
|---|---|
| Email Addresses | Adds to the existing list. Case-insensitive, so an address already on the record is not duplicated. |
| Phone Numbers | Adds a number to the existing list if it is not already there. The number lands with no type, which Lever shows as Other. |
| Mobile / Work / Home Phone | Replaces the first number of that type. A candidate with three mobile numbers shows and updates only the first. |
| Links, Tags | Adds to the existing list. |
| Name, Headline, Location, Stage | Replaces the current value. |
An update never removes a value. You cannot drop an email address, phone number, tag, or link from a workflow.
The Note object is create-only. Two fields are required, Candidate Record ID and Note Content, and both have to be mapped for the note to reach the candidate.
Open the Docusign App Center and search for Lever in the search bar.
Click the Lever 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.
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.
Sign in to Lever if you are not signed in already. Lever names the app Docusign IAM for Lever.
On the Lever consent screen, click Accept.
The connection is added and ready to use in workflow steps.
The Lever consent screen appears every time you create a connection.
On the Lever 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.
In Lever, open Settings → Integrations and API → Authorized Apps and revoke Docusign IAM for Lever. That stops every Docusign connection created by that Lever user.
Log in to Docusign and go to Agreements → Workflows.
Click Create Workflow.
Build your workflow using the available steps, including the Lever actions.
Publish the workflow when it is ready.
Click + Add Step and search for Lever:
A typical hiring flow:
Read from Lever find the candidate
Prepare eSignature Template pre-fill the offer letter
Send Documents for Signature
File Upload to Lever attach the signed offer to the candidate
Writeback to Lever move the stage, add a tag, or post a note
Job postings are read-only. There is no writeback to a posting.
The Read from Lever step retrieves a record and exposes its fields as workflow variables.
In this example the workflow starts From an API Call and receives the ID of the record to read.
On the workflow canvas, click Add workflow start.
Select a method: choose From an API Call.
Set up variables: add a Text variable named object_id.
Process type: choose Automated process.
Once published, the workflow has a URL your external system calls, passing object_id.
On the workflow canvas, click + Add a step below Start Workflow.
Search for Lever and select Read from Lever.
Connection: select the connection you created during installation.
Lever object: choose Candidate or Job Posting. 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, Headline, Email Addresses, First Email, Second Email, Phone Numbers, Mobile Phone, Work Phone, Home Phone, Location, Links, Tags, Sources, Origin, Stage, Owner Email, Owner Name, Job Posting Title, Lever Profile URL, Created At, Last Interaction At.
Job Posting: Record ID, Job Title, State, Team, Department, Location, Work type, Location type, Tags, Posting Owner Name, Posting Owner Email, Hiring Manager Name, Hiring Manager Email, Salary Range Minimum, Salary Range Maximum, Salary Currency, Salary Interval, Salary Description, Posting URL, Apply URL, Created At.
These fields return a set value, not free text:
| Field | Value |
|---|---|
| Origin | One of agency, applied, internal, referred, sourced, university. |
| Location type | remote, onsite, or hybrid. |
| Work type | A value from your Lever workspace, for example Full-time. |
| Salary Interval | A machine value such as per-year-salary, not the / year shown in Lever. |
Posting URL and Apply URL are two different links: the public job page and the application page.
Department stays empty unless your Lever account uses departments. Team is populated either way.
Click Next.
Create a rule that tells the step which record to read. In this example, match the Lever Record ID to the object_id variable from the workflow start:
object_idUnder How many records should this step return?, pick one:
Use preview this step to check the rule against live data. Click Apply.
Searchable fields are Record ID, Email Addresses, Tags, Sources, Origin, Stage, and Job Posting Title for a candidate, and Record ID, Job Title, State, and Tags for a job posting. Every other field stops the workflow step.
The Writeback to Lever step updates a candidate, creates one, or posts a note.
Check what an update does to each field first: some fields replace their value and some add to a list.
On the workflow canvas, click + Add a step where the writeback belongs, for example below a Collect Data with Web Forms step.
Search for Lever and select Writeback to Lever.
Connection: select your Lever connection.
Lever object: choose Candidate 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 then gets its own row. Map it to the workflow variable that supplies the value.
Writable Candidate fields: Name*, Headline, Email Addresses, Phone Numbers, Mobile Phone, Work Phone, Home Phone, Location, Links, Tags, Stage.
* Name is a required field. To change a name the candidate already has, tick Overwrite if field value exists on it.
⚠️ Map from the right source. The variable picker also lists the output of your Read from Lever step. Mapping from there writes the original values back unchanged. Map from the step that collected the new data, such as Collect Data with Web Forms.
Click Next.
The Writeback step does no searching of its own, so it addresses the candidate by a Record ID carried from an earlier step.
Click Apply.
Leaving the Record ID empty under Update or Create creates a candidate.
Select Note as the Lever object.
Create is the only write setting.
Map both required fields, Candidate Record ID and Note Content.
The File Upload to Lever step attaches a document produced earlier in the workflow to a candidate's Files tab. Maximum size is 30 MB.
Add a step after signing completes, search for Lever, and select File Upload to Lever.
Choose the file or envelope from an earlier step. In this example it is 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 Lever connection.
Select drive: Candidates is the only drive.
Click Add Folder.
The folder holds the candidate's Record ID. Lever creates no 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, then select Record ID and click Add.
The variable appears in the Folder name field.
Select folder now shows the Record ID variable. Click Next.
The app reads the last segment of the path, so a subfolder overrides the folder above it. Plain text in the folder and the Record ID in a subfolder still reaches the right candidate.
We do not recommend it. Put the Record ID in the folder and leave the subfolder out.
Build the file name from Add Text and Add Variable. A timestamp variable keeps repeat runs from producing identical names.
The app replaces anything outside letters, digits, dots, and hyphens with _, so 2026-08-21T08:20:32.706Z is stored as 2026-08-21T08_20_32.706Z.
Click Apply. The file lands on the candidate's Files tab, marked Related to their job.
Q: The Lever consent screen appears every time I create a connection. Did the last one fail?
A: No. Check Manage Connections; the earlier connections are still Active.
Q: The step fails with Request failed with status code 400 and no other detail.
A: Docusign collapses every non-2xx response to that message. On a Read step:
| Likely cause | Check |
|---|---|
| Searching on a field that is not searchable | Use Record ID, Email Addresses, Tags, Sources, Origin, Stage, or Job Posting Title. For a posting: Record ID, Job Title, State, Tags. |
| An operator other than Equal to | Change it to Equal to. |
| Two conditions on the same field | Keep one. |
| A stage name that does not exist | Compare it with the stage list in Lever. Stages resolve by name. |
Q: Why can't I search by candidate name?
A: Name is not a searchable field. Match on Record ID, or on Email Addresses when the ID is not available.
Q: Why does the Tags variable hold more tags than the candidate profile shows?
A: Lever adds the posting's title, team, and location as automatic tags. See Tags include Lever's automatic posting tags.
Q: I created a candidate and Lever saved a different name.
A: One of the email addresses already belonged to a contact, so Lever attached the new application to that person and kept their existing name.
Q: I wrote a phone number and the old one is still there.
A: Phone Numbers adds to the list. To replace a number, write to Mobile Phone, Work Phone, or Home Phone.
Q: How do I remove a tag, a link, or an email address?
A: Not from a workflow. Those fields only add. Remove the value in Lever.
Q: The location I wrote back does not match what the Read step returns.
A: Lever normalizes a location against its own geography and stores its own version of the string, so Houston, TX, USA comes back as Houston, Texas, USA.
Q: I created a candidate and the profile says "No job selected yet".
A: The writeback form has no Job Posting Title field, so a recruiter assigns the job in Lever.
Q: The file picker says no files are available.
A: No earlier step in the workflow produced a file. Add the upload after Send Documents for Signature.
Q: The file did not appear on the candidate.
A: Check that the folder holds the candidate's Record ID variable rather than a name or a static value, and that the step supplying it runs before the upload.